iconv.1: New page for iconv(1)

Hi,

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Quoted 1 line

From 006b3e251ae3883b3652bfb3f32a8d72ba803960 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Mon, 9 Jun 2014 08:09:57 +0300
Subject: [PATCH] iconv.1: New page for iconv(1)

---
 man1/iconv.1 |  156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 156 insertions(+), 0 deletions(-)
 create mode 100644 man1/iconv.1

man1/iconv.1 new file +29 -0

new file mode 100644
index 0000000..ece7e6a
@@ -0,0 +1,156 @@
+'\" t -*- coding: UTF-8 -*-
+.\"
+.\" Copyright (C) 2014 Marko Myllynen <[email protected]>
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
+.\"
+.TH ICONV 1 2014-06-06 "GNU" "Linux User Manual"
+.SH NAME
+iconv \- convert text from one character encoding to another
+.SH SYNOPSIS

man1/iconv.1 new file +16 -0

+.SH OPTIONS
+.TP
+.BI \-f " from-encoding" ", \-\-from-code=" from-encoding
+Use
+.I from-encoding
+for input characters.
+.TP
+.BI \-t " to-encoding" ", \-\-to-code=" to-encoding
+Use
+.I to-encoding
+for output characters.
+
+If
+.I to-encoding
+is appended with
+.BR //IGNORE ,

man1/iconv.1 new file +8 -0

+multiple files.
+.TP
+.B "\-\-help"
+Print a usage summary and exit.
+.TP
+.B "\-\-usage"
+Print a short usage summary and exit.
+.TP

man1/iconv.1 new file +13 -0

+.SH FILES
+.TP
+.I /usr/lib/gconv
+Usual default gconv module path.
+.TP
+.I /usr/lib/gconv/gconv-modules
+Usual default gconv module configuration.
+.TP
+.I /usr/lib/gconv/gconv-modules.cache
+Usual default gconv module configuration cache.
+.SH CONFORMING TO
+POSIX.1-2001.
+.SH EXAMPLE

man1/iconv.1 new file +8 -0

+.PP
+.RS
+echo abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT
+.RE
+.SH "SEE ALSO"
+.BR locale (1),
+.BR charsets (7),
+.BR iconvconfig (8)

Quoted 3 lines · Marko Myllynen

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

Hi,

Quoted 2 lines · Michael Kerrisk (man-pages)

Quoted 1 line · Marko Myllynen

Quoted 5 lines

Quoted 2 lines

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

ok, please see below, hopefully the explanation are now clearer without going into too low level details.

+.SH ENVIRONMENT

man1/iconv.1 new file +6 -0

+Internally, the
+.B iconv
+program uses the
+.BR iconv (3)
+function which in turn uses
+.I gconv

Quoted 11 lines · Marko Myllynen

Quoted 7 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

ok, please see below, hopefully the explanation are now clearer without going into too low level details.

Yes, thanks, a lot better. I have applied this, but have a question, below.

Quoted 13 lines

+.SH ENVIRONMENT

man1/iconv.1 new file +12 -0

+Internally, the
+.B iconv
+program uses the
+.BR iconv (3)
+function which in turn uses
+.I gconv
+modules to convert to and from a character set.
+.B iconv
+supports any character set for which a
+corresponding gconv configuration and module are provided for.
+By default, the system provided gconv configuration and modules
+are used, but

man1/iconv.1 line 132

Quoted 4 lines

+.B GCONV_PATH

man1/iconv.1 new file +3 -0

+can be defined as a list of pathnames, separated by colons (\(aq:\(aq),
+for gconv configuration and module search path,
+to be searched prior to the system provided configuration and modules.

That last sentence is long and hard to parse. What exactly is GCONV_PATH? Is it a list of configuration paths? module search paths? I am left uncertain after reading that sentence.

Hi,

Quoted 28 lines · Michael Kerrisk (man-pages)

Quoted 11 lines · Marko Myllynen

Quoted 7 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

ok, please see below, hopefully the explanation are now clearer without going into too low level details.

Yes, thanks, a lot better. I have applied this, but have a question, below.

Quoted 13 lines

+.SH ENVIRONMENT

man1/iconv.1 new file +12 -0

+Internally, the
+.B iconv
+program uses the
+.BR iconv (3)
+function which in turn uses
+.I gconv
+modules to convert to and from a character set.
+.B iconv
+supports any character set for which a
+corresponding gconv configuration and module are provided for.
+By default, the system provided gconv configuration and modules
+are used, but

Quoted 8 lines

man1/iconv.1 line 132

Quoted 4 lines

+.B GCONV_PATH

man1/iconv.1 new file +3 -0

+can be defined as a list of pathnames, separated by colons (\(aq:\(aq),
+for gconv configuration and module search path,
+to be searched prior to the system provided configuration and modules.

That last sentence is long and hard to parse. What exactly is GCONV_PATH? Is it a list of configuration paths? module search paths? I am left uncertain after reading that sentence.

yeah, I think I was trying to make a long story too short.

When a program, such as iconv(1), uses iconv(3) (the function), it first needs to allocate a conversion descriptor with iconv_open(3) and during the iconv_open() call glibc, if GCONV_PATH is not set, loads the system gconv cache file created by iconvconfig(8) and based on the configuration then loads the needed gconv modules for conversion (an example of a gconv module is CP1252.so). If GCONV_PATH is set, glibc first tries to load the configuration files from the paths in GCONV_PATH followed by the system configuration file. If a directory does not contain a gconv module configuration file, possible gconv modules in it are ignored. If a directory contains a gconv module configuration file and it is determined that a needed module for this conversion is available in the directory, then the needed module is loaded from there, the order being so that the first suitable module found in GCONV_PATH is used. This allows users to use custom modules and even replace system provided modules by providing such modules in GCONV_PATH directories.

Quoted 40 lines · Marko Myllynen

Quoted 28 lines · Michael Kerrisk (man-pages)

Quoted 11 lines · Marko Myllynen

Quoted 7 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

ok, please see below, hopefully the explanation are now clearer without going into too low level details.

Yes, thanks, a lot better. I have applied this, but have a question, below.

Quoted 13 lines

+.SH ENVIRONMENT

(quoted diff) +12 -0

+Internally, the
+.B iconv
+program uses the
+.BR iconv (3)
+function which in turn uses
+.I gconv
+modules to convert to and from a character set.
+.B iconv
+supports any character set for which a
+corresponding gconv configuration and module are provided for.
+By default, the system provided gconv configuration and modules
+are used, but

Quoted 8 lines

Review

Quoted 4 lines

+.B GCONV_PATH

(quoted diff) +3 -0

+can be defined as a list of pathnames, separated by colons (\(aq:\(aq),
+for gconv configuration and module search path,
+to be searched prior to the system provided configuration and modules.

That last sentence is long and hard to parse. What exactly is GCONV_PATH? Is it a list of configuration paths? module search paths? I am left uncertain after reading that sentence.

yeah, I think I was trying to make a long story too short.

Quoted 15 lines

When a program, such as iconv(1), uses iconv(3) (the function), it first needs to allocate a conversion descriptor with iconv_open(3) and during the iconv_open() call glibc, if GCONV_PATH is not set, loads the system gconv cache file created by iconvconfig(8) and based on the configuration then loads the needed gconv modules for conversion (an example of a gconv module is CP1252.so). If GCONV_PATH is set, glibc first tries to load the configuration files from the paths in GCONV_PATH followed by the system configuration file. If a directory does not contain a gconv module configuration file, possible gconv modules in it are ignored. If a directory contains a gconv module configuration file and it is determined that a needed module for this conversion is available in the directory, then the needed module is loaded from there, the order being so that the first suitable module found in GCONV_PATH is used. This allows users to use custom modules and even replace system provided modules by providing such modules in GCONV_PATH directories.

It sounds like you mean the above paragraph should be added to the page. Is that correct?

Hi,

Quoted 57 lines · Michael Kerrisk (man-pages)

Quoted 55 lines · Marko Myllynen

Quoted 28 lines · Michael Kerrisk (man-pages)

Quoted 11 lines · Marko Myllynen

Quoted 7 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen

while updating the locale pages I noticed there was no iconv(1) page in upstream so I wrote one, please see below.

Thanks for doing this. Could I ask you to look at the comments below, and send a revised version, please.

ok, please see below, hopefully the explanation are now clearer without going into too low level details.

Yes, thanks, a lot better. I have applied this, but have a question, below.

Quoted 13 lines

+.SH ENVIRONMENT

(quoted diff) +12 -0

+Internally, the
+.B iconv
+program uses the
+.BR iconv (3)
+function which in turn uses
+.I gconv
+modules to convert to and from a character set.
+.B iconv
+supports any character set for which a
+corresponding gconv configuration and module are provided for.
+By default, the system provided gconv configuration and modules
+are used, but

Quoted 8 lines

Review

Quoted 4 lines

+.B GCONV_PATH

(quoted diff) +3 -0

+can be defined as a list of pathnames, separated by colons (\(aq:\(aq),
+for gconv configuration and module search path,
+to be searched prior to the system provided configuration and modules.

That last sentence is long and hard to parse. What exactly is GCONV_PATH? Is it a list of configuration paths? module search paths? I am left uncertain after reading that sentence.

yeah, I think I was trying to make a long story too short.

When a program, such as iconv(1), uses iconv(3) (the function), it first needs to allocate a conversion descriptor with iconv_open(3) and during the iconv_open() call glibc, if GCONV_PATH is not set, loads the system gconv cache file created by iconvconfig(8) and based on the configuration then loads the needed gconv modules for conversion (an example of a gconv module is CP1252.so). If GCONV_PATH is set, glibc first tries to load the configuration files from the paths in GCONV_PATH followed by the system configuration file. If a directory does not contain a gconv module configuration file, possible gconv modules in it are ignored. If a directory contains a gconv module configuration file and it is determined that a needed module for this conversion is available in the directory, then the needed module is loaded from there, the order being so that the first suitable module found in GCONV_PATH is used. This allows users to use custom modules and even replace system provided modules by providing such modules in GCONV_PATH directories.

Quoted 2 lines

It sounds like you mean the above paragraph should be added to the page. Is that correct?

I was more like providing all the details and wasn't thinking to include the paragraph at least as-is. But if you think it seems suitable to be added, please go ahead. I'd personally prefer a more compact version but compacting the message without losing precision in this case seems a bit hard.

Quoted 6 lines · Marko Myllynen

Quoted 5 lines · Michael Kerrisk (man-pages)

Quoted 4 lines · Marko Myllynen

Quoted 3 lines · Michael Kerrisk (man-pages)

Quoted 2 lines · Marko Myllynen

Quoted 1 line · Michael Kerrisk (man-pages)

On 06/10/2014 10:38 AM, Marko Myllynen wrote:

So, how does the following look to you:

ENVIRONMENT
Internally, the iconv program uses the iconv(3) function which
in turn uses gconv modules (dynamically loaded shared
libraries) to convert to and from a character set. Before
calling iconv(3), the iconv program must first allocate a con‐ version descriptor using iconv_open(3). The operation of the latter function is influenced by the setting of the GCONV_PATH environment variable:

* If GCONV_PATH is not set, iconv_open(3) loads the system gconv cache file created by iconvconfig(8) and then, based on the configuration, loads the gconv modules needed to per‐ form the conversion.

* If GCONV_PATH is defined (as a colon-separated list of path‐ names), the system gconv module configuration cache is not
used. Instead, iconv_open(3) first tries to load the con‐
figuration files from one of the directories in GCONV_PATH, followed by the system configuration file. If a directory does not contain a gconv module configuration file, any gconv modules that it may contain are ignored. If a direc‐ tory contains a gconv module configuration file and it is determined that a module needed for this conversion is available in the directory, then the needed module is loaded from that directory, the order being such that the first
suitable module found in GCONV_PATH is used. This allows
users to use custom modules and even replace system-provided modules by providing such modules in GCONV_PATH directories.

iconv supports any character set for which a corresponding gconv configuration and module are provided.

I have two doubts about the above text:

* What is "the system configuration file"?

* The last sentence (left over from your earlier text) seems out of place. Is it needed? If it is, I think we need a better place for it.

Hi,

Quoted 9 lines · Michael Kerrisk (man-pages)

Quoted 6 lines · Marko Myllynen

Quoted 5 lines · Michael Kerrisk (man-pages)

Quoted 4 lines · Marko Myllynen

Quoted 3 lines · Michael Kerrisk (man-pages)

Quoted 2 lines · Marko Myllynen

Quoted 1 line · Michael Kerrisk (man-pages)

On 06/10/2014 10:38 AM, Marko Myllynen wrote:

So, how does the following look to you:

it looks very good, thanks for this!

Quoted 29 lines

ENVIRONMENT
Internally, the iconv program uses the iconv(3) function which
in turn uses gconv modules (dynamically loaded shared
libraries) to convert to and from a character set. Before
calling iconv(3), the iconv program must first allocate a con‐ version descriptor using iconv_open(3). The operation of the latter function is influenced by the setting of the GCONV_PATH environment variable:

* If GCONV_PATH is not set, iconv_open(3) loads the system gconv cache file created by iconvconfig(8) and then, based on the configuration, loads the gconv modules needed to per‐ form the conversion.

* If GCONV_PATH is defined (as a colon-separated list of path‐ names), the system gconv module configuration cache is not
used. Instead, iconv_open(3) first tries to load the con‐
figuration files from one of the directories in GCONV_PATH, followed by the system configuration file. If a directory does not contain a gconv module configuration file, any gconv modules that it may contain are ignored. If a direc‐ tory contains a gconv module configuration file and it is determined that a module needed for this conversion is available in the directory, then the needed module is loaded from that directory, the order being such that the first
suitable module found in GCONV_PATH is used. This allows
users to use custom modules and even replace system-provided modules by providing such modules in GCONV_PATH directories.

Quoted 6 lines

iconv supports any character set for which a corresponding gconv configuration and module are provided.

I have two doubts about the above text:

* What is "the system configuration file"?

It is listed in the FILES section, does that clarify enough?

Quoted 3 lines

* The last sentence (left over from your earlier text) seems out of place. Is it needed? If it is, I think we need a better place for it.

I think the same thing is already said (albeit slightly less explicitly) above it so I don't think it's needed anymore.

Quoted 35 lines

Quoted 35 lines

ENVIRONMENT
Internally, the iconv program uses the iconv(3) function which
in turn uses gconv modules (dynamically loaded shared
libraries) to convert to and from a character set. Before
calling iconv(3), the iconv program must first allocate a con‐ version descriptor using iconv_open(3). The operation of the latter function is influenced by the setting of the GCONV_PATH environment variable:

* If GCONV_PATH is not set, iconv_open(3) loads the system gconv cache file created by iconvconfig(8) and then, based on the configuration, loads the gconv modules needed to per‐ form the conversion.

* If GCONV_PATH is defined (as a colon-separated list of path‐ names), the system gconv module configuration cache is not
used. Instead, iconv_open(3) first tries to load the con‐
figuration files from one of the directories in GCONV_PATH, followed by the system configuration file. If a directory does not contain a gconv module configuration file, any gconv modules that it may contain are ignored. If a direc‐ tory contains a gconv module configuration file and it is determined that a module needed for this conversion is available in the directory, then the needed module is loaded from that directory, the order being such that the first
suitable module found in GCONV_PATH is used. This allows
users to use custom modules and even replace system-provided modules by providing such modules in GCONV_PATH directories.

iconv supports any character set for which a corresponding gconv configuration and module are provided.

I have two doubts about the above text:

Quoted 3 lines

Quoted 1 line

* What is "the system configuration file"?

It is listed in the FILES section, does that clarify enough?

I wondered about that. But the term "system configuration file" does not appear in FILES. Is it "Usual default gconv module configuration"? If so, that's not so obvious because the terms differ.

Hi,

Quoted 37 lines · Michael Kerrisk (man-pages)

Quoted 37 lines

Quoted 36 lines

ENVIRONMENT
Internally, the iconv program uses the iconv(3) function which
in turn uses gconv modules (dynamically loaded shared
libraries) to convert to and from a character set. Before
calling iconv(3), the iconv program must first allocate a con‐ version descriptor using iconv_open(3). The operation of the latter function is influenced by the setting of the GCONV_PATH environment variable:

* If GCONV_PATH is not set, iconv_open(3) loads the system gconv cache file created by iconvconfig(8) and then, based on the configuration, loads the gconv modules needed to per‐ form the conversion.

* If GCONV_PATH is defined (as a colon-separated list of path‐ names), the system gconv module configuration cache is not
used. Instead, iconv_open(3) first tries to load the con‐
figuration files from one of the directories in GCONV_PATH, followed by the system configuration file. If a directory does not contain a gconv module configuration file, any gconv modules that it may contain are ignored. If a direc‐ tory contains a gconv module configuration file and it is determined that a module needed for this conversion is available in the directory, then the needed module is loaded from that directory, the order being such that the first
suitable module found in GCONV_PATH is used. This allows
users to use custom modules and even replace system-provided modules by providing such modules in GCONV_PATH directories.

iconv supports any character set for which a corresponding gconv configuration and module are provided.

I have two doubts about the above text:

* What is "the system configuration file"?

Quoted 5 lines

Quoted 1 line

It is listed in the FILES section, does that clarify enough?

I wondered about that. But the term "system configuration file" does not appear in FILES. Is it "Usual default gconv module configuration"? If so, that's not so obvious because the terms differ.

you're right, using "system default gconv module configuration" in both places should make it obvious.