iconvconfig.8: New page for iconvconfig(8)

PATCH In review Marko Myllynen 2 participants 5 messages Jun 10, 2014 – Jun 11, 2014 4 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Marko Myllynen

author

2014-06-10 08:39 UTC #0 lore raw

PATCH 1/1 iconvconfig.8: New page for iconvconfig(8)

Hi,

while writing the iconv(1) page I noticed there was no page for iconvconfig(8) so I wrote one, please see below.

Quoted 1 line

From 566561b63db0fe709570d3c5aca6262065d64f71 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Mon, 9 Jun 2014 17:10:12 +0300
Subject: [PATCH] iconvconfig.8: New page for iconvconfig(8)

---
 man8/iconvconfig.8 |   86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 86 insertions(+), 0 deletions(-)
 create mode 100644 man8/iconvconfig.8

man8/iconvconfig.8 new file +86 -0

new file mode 100644
index 0000000..db7d926
@@ -0,0 +1,86 @@
+'\" 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 ICONVCONFIG 8 2014-06-09 "GNU" "Linux System Administration"
+.SH NAME
+iconvconfig \- create iconv module configuration cache
+.SH SYNOPSIS
+.B iconvconfig
+.RI [ options ]
+.RI [ directory ]...
+.SH DESCRIPTION
+The
+.B iconvconfig
+program reads iconv module configuration files and writes
+a fastloading iconv module configuration cache file.
+Only the system default cache file is used by programs like
+.BR iconv (1),
+caching is disabled when additional gconv module directories
+are specified with the environment variable
+.BR GCONV_PATH .
+.SH OPTIONS
+.TP
+.B "\-\-nostdlib"
+Do not search the system default gconv directory,
+only those provided on the command line.
+.TP
+.BI \-o " outputfile" ", \-\-output=" outputfile
+Use
+.I outputfile
+for output instead of the system default cache location.
+.TP
+.BI \-\-prefix= pathname
+Set the prefix to be prepended to the system pathnames.
+By default, the prefix is empty.
+Setting the prefix to
+.IR foo ,
+the gconv module configuration would be read from
+.IR foo/usr/lib/gconv/gconv-modules
+and the cache would be written to
+.IR foo/usr/lib/gconv/gconv-modules.cache .
+.TP
+.B "\-\-help"
+Print a usage summary and exit.
+.TP
+.B "\-\-usage"
+Print a short usage summary and exit.
+.TP
+.B "\-V, \-\-version"
+Print the version number, license, and disclaimer of warranty for
+.BR iconv .
+.SH EXIT STATUS
+Zero on success, non-zero on errors.
+.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 "SEE ALSO"
+.BR iconv (1)

Signature · 10 lines

1.7.1

Thanks,

-- 
Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2014-06-10 19:43 UTC #2 lore raw

Hi Marko,

Quoted 4 lines · Marko Myllynen

Hi,
while writing the iconv(1) page I noticed there was no page for iconvconfig(8) so I wrote one, please see below.

Thanks.

Again, some comments below. Could you address and send a v2, please.

Quoted 43 lines

Quoted 1 line

From 566561b63db0fe709570d3c5aca6262065d64f71 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Mon, 9 Jun 2014 17:10:12 +0300
Subject: [PATCH] iconvconfig.8: New page for iconvconfig(8)

---
 man8/iconvconfig.8 |   86 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 86 insertions(+), 0 deletions(-)
 create mode 100644 man8/iconvconfig.8

man8/iconvconfig.8 new file +27 -0

new file mode 100644
index 0000000..db7d926
@@ -0,0 +1,86 @@
+'\" 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 ICONVCONFIG 8 2014-06-09 "GNU" "Linux System Administration"
+.SH NAME

man8/iconvconfig.8 line 37

Quoted 10 lines

man8/iconvconfig.8 new file +10 -0

+iconvconfig \- create iconv module configuration cache
+.SH SYNOPSIS
+.B iconvconfig
+.RI [ options ]
+.RI [ directory ]...
+.SH DESCRIPTION
+The
+.B iconvconfig
+program reads iconv module configuration files and writes
+a fastloading iconv module configuration cache file.

It's not completely clear from the preceding sentence what the purpose of iconvconfig is. I think the reader needs some help to:
* know what "iconv module configuration"
* what uses the cache file

man8/iconvconfig.8 line 42

Quoted 5 lines

man8/iconvconfig.8 new file +5 -0

+Only the system default cache file is used by programs like
+.BR iconv (1),
+caching is disabled when additional gconv module directories
+are specified with the environment variable
+.BR GCONV_PATH .

The preceding sentence seems to cover two unrelated ideas. Could you split and expand please. Also, the significance of "Only the system default cache file is used"? It's not clear...

man8/iconvconfig.8 line 47

Quoted 5 lines

man8/iconvconfig.8 new file +5 -0

+.SH OPTIONS
+.TP
+.B "\-\-nostdlib"
+Do not search the system default gconv directory,
+only those provided on the command line.

s/those/the directories/ ?

man8/iconvconfig.8 line 55

Quoted 8 lines

man8/iconvconfig.8 new file +8 -0

+.TP
+.BI \-o " outputfile" ", \-\-output=" outputfile
+Use
+.I outputfile
+for output instead of the system default cache location.
+.TP
+.BI \-\-prefix= pathname
+Set the prefix to be prepended to the system pathnames.

"system pathnames" needs some explanation, I think. What are they? This might be as simple as adding "See FILES, below."

Cheers,

Michael

Quoted 32 lines

man8/iconvconfig.8 new file +31 -0

+By default, the prefix is empty.
+Setting the prefix to
+.IR foo ,
+the gconv module configuration would be read from
+.IR foo/usr/lib/gconv/gconv-modules
+and the cache would be written to
+.IR foo/usr/lib/gconv/gconv-modules.cache .
+.TP
+.B "\-\-help"
+Print a usage summary and exit.
+.TP
+.B "\-\-usage"
+Print a short usage summary and exit.
+.TP
+.B "\-V, \-\-version"
+Print the version number, license, and disclaimer of warranty for
+.BR iconv .
+.SH EXIT STATUS
+Zero on success, non-zero on errors.
+.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 "SEE ALSO"
+.BR iconv (1)

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Marko Myllynen

author

2014-06-11 08:09 UTC #4 lore raw

Hi,

Quoted 6 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen
while writing the iconv(1) page I noticed there was no page for iconvconfig(8) so I wrote one, please see below.
Again, some comments below. Could you address and send a v2, please.

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

Quoted 1 line

From 01f14067fc7769b750c431c0c0b0f60a43e001d6 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Wed, 11 Jun 2014 08:40:05 +0300
Subject: [PATCH] iconvconfig.8: New page for iconvconfig(8)

---
 man8/iconvconfig.8 |  101 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 101 insertions(+), 0 deletions(-)
 create mode 100644 man8/iconvconfig.8

man8/iconvconfig.8 new file +101 -0

new file mode 100644
index 0000000..0c3afe8
@@ -0,0 +1,101 @@
+'\" 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 ICONVCONFIG 8 2014-06-09 "GNU" "Linux System Administration"
+.SH NAME
+iconvconfig \- create iconv module configuration cache
+.SH SYNOPSIS
+.B iconvconfig
+.RI [ options ]
+.RI [ directory ]...
+.SH DESCRIPTION
+The
+.BR iconv(3)
+function internally uses
+.I gconv
+modules to convert to and from a character set.
+A configuration file is used to determine the needed modules
+for a conversion.
+Loading and parsing such a configuration file would slow down
+.BR iconv(3)
+using programs so a caching mechanism has been introduced.
+
+The
+.B iconvconfig
+program reads iconv module configuration files and writes
+a fastloading gconv module configuration cache file.
+In addition to the system provided gconv modules, user can specify 
+custom gconv module directories with the environment variable
+.BR GCONV_PATH .
+However, iconv module configuration caching is only used when
+the environment variable
+.BR GCONV_PATH
+is not set.
+.SH OPTIONS
+.TP
+.B "\-\-nostdlib"
+Do not search the system default gconv directory,
+only the directories provided on the command line.
+.TP
+.BI \-o " outputfile" ", \-\-output=" outputfile
+Use
+.I outputfile
+for output instead of the system default cache location.
+.TP
+.BI \-\-prefix= pathname
+Set the prefix to be prepended to the system pathnames.
+See FILES, below.
+By default, the prefix is empty.
+Setting the prefix to
+.IR foo ,
+the gconv module configuration would be read from
+.IR foo/usr/lib/gconv/gconv-modules
+and the cache would be written to
+.IR foo/usr/lib/gconv/gconv-modules.cache .
+.TP
+.B "\-\-help"
+Print a usage summary and exit.
+.TP
+.B "\-\-usage"
+Print a short usage summary and exit.
+.TP
+.B "\-V, \-\-version"
+Print the version number, license, and disclaimer of warranty for
+.BR iconv .
+.SH EXIT STATUS
+Zero on success, non-zero on errors.
+.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 "SEE ALSO"
+.BR iconv (1),
+.BR iconv (3)

Signature · 10 lines

1.7.1

Thanks,

-- 
Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk (man-pages)

2014-06-11 10:29 UTC #6 lore raw

Hi Marko,

Quoted 67 lines · Marko Myllynen

Hi,

Quoted 6 lines · Michael Kerrisk (man-pages)

Quoted 3 lines · Marko Myllynen
while writing the iconv(1) page I noticed there was no page for iconvconfig(8) so I wrote one, please see below.
Again, some comments below. Could you address and send a v2, please.

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

Quoted 1 line

From 01f14067fc7769b750c431c0c0b0f60a43e001d6 Mon Sep 17 00:00:00 2001

From: Marko Myllynen <[email protected]>
Date: Wed, 11 Jun 2014 08:40:05 +0300
Subject: [PATCH] iconvconfig.8: New page for iconvconfig(8)

---
 man8/iconvconfig.8 |  101 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 101 insertions(+), 0 deletions(-)
 create mode 100644 man8/iconvconfig.8

man8/iconvconfig.8 new file +38 -0

new file mode 100644
index 0000000..0c3afe8
@@ -0,0 +1,101 @@
+'\" 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 ICONVCONFIG 8 2014-06-09 "GNU" "Linux System Administration"
+.SH NAME
+iconvconfig \- create iconv module configuration cache
+.SH SYNOPSIS
+.B iconvconfig
+.RI [ options ]
+.RI [ directory ]...
+.SH DESCRIPTION
+The
+.BR iconv(3)
+function internally uses
+.I gconv
+modules to convert to and from a character set.

man8/iconvconfig.8 line 48

Quoted 10 lines

man8/iconvconfig.8 new file +10 -0

+A configuration file is used to determine the needed modules
+for a conversion.
+Loading and parsing such a configuration file would slow down
+.BR iconv(3)
+using programs so a caching mechanism has been introduced.
+
+The
+.B iconvconfig
+program reads iconv module configuration files and writes
+a fastloading gconv module configuration cache file.

I see that since you wrote the last version, you did a s/iconv/gconv/ in the above line. That typo really confused me before; now things make more sense.

Patch applied. Thanks for the new page!

Cheers,

Michael

Signature · 7 lines

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Marko Myllynen

author

2014-06-11 13:27 UTC #8 lore raw

Hi,

Quoted 9 lines · Michael Kerrisk (man-pages)

Quoted 8 lines · Marko Myllynen
Quoted 6 lines · Michael Kerrisk (man-pages)
Quoted 3 lines · Marko Myllynen
while writing the iconv(1) page I noticed there was no page for iconvconfig(8) so I wrote one, please see below.
Again, some comments below. Could you address and send a v2, please.

Quoted 7 lines

Quoted 3 lines
ok, please see below, hopefully the explanation are now clearer without going into too low level details.
+a fastloading gconv module configuration cache file.
I see that since you wrote the last version, you did a s/iconv/gconv/ in the above line. That typo really confused me before; now things make more sense.

I'm not sure does it really classify as a typo, it's more like that gconv = GNU (C library) iconv implementation, they can often be used interchangeably. It's indeed a bit confusing but sticking with one or the other is a bit hard given that the program name is iconv and the environment variable is GCONV_PATH.

Thanks,

Signature · 5 lines

Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html