* Consistency fixes in util-linux man pages @ 2020-05-16 8:24 Michael Kerrisk (man-pages) 2020-05-18 8:28 ` Karel Zak 0 siblings, 1 reply; 6+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-16 8:24 UTC (permalink / raw) To: Karel Zak; +Cc: mtk.manpages, util-linux, Helge Kreutzmann Hello Karel, Perhaps a little inspired by Helge's recent reports, I wonder about submitting some wide-ranging patches to improve consistency across the util-linux manual pages. As an example, there's quite a bit of variation in the order of .SH sections in the manual pages (e.g., in the placement of the SEE ALSO section). The pages would be more readable if the ordering was more consistent. Would you entertain patches that made wide-ranging changes that fixed that sort of thing (without changing page content? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Consistency fixes in util-linux man pages 2020-05-16 8:24 Consistency fixes in util-linux man pages Michael Kerrisk (man-pages) @ 2020-05-18 8:28 ` Karel Zak 2020-05-18 10:36 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 6+ messages in thread From: Karel Zak @ 2020-05-18 8:28 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: util-linux, Helge Kreutzmann On Sat, May 16, 2020 at 10:24:59AM +0200, Michael Kerrisk (man-pages) wrote: > Hello Karel, > > Perhaps a little inspired by Helge's recent reports, I wonder about > submitting some wide-ranging patches to improve consistency across > the util-linux manual pages. > > As an example, there's quite a bit of variation in the order of > .SH sections in the manual pages (e.g., in the placement of the SEE > ALSO section). The pages would be more readable if the ordering was > more consistent. > > Would you entertain patches that made wide-ranging changes > that fixed that sort of thing (without changing page content? No problem, but it would be nice to somehow document that is expected to avoid future changes in an opposite way. For example add some info to Documentation/howto-man-page.txt. BTW, I'm not sure about man pages as ideal format to maintain documentation (because it's mostly about formatting than about content). I think about AsciiDoc or so in future. What do you think about this idea? Karel -- Karel Zak <kzak@redhat.com> http://karelzak.blogspot.com ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Consistency fixes in util-linux man pages 2020-05-18 8:28 ` Karel Zak @ 2020-05-18 10:36 ` Michael Kerrisk (man-pages) 2020-05-18 15:03 ` Helge Kreutzmann 0 siblings, 1 reply; 6+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-05-18 10:36 UTC (permalink / raw) To: Karel Zak; +Cc: util-linux, Helge Kreutzmann Hello Karel, On Mon, 18 May 2020 at 10:28, Karel Zak <kzak@redhat.com> wrote: > > On Sat, May 16, 2020 at 10:24:59AM +0200, Michael Kerrisk (man-pages) wrote: > > Hello Karel, > > > > Perhaps a little inspired by Helge's recent reports, I wonder about > > submitting some wide-ranging patches to improve consistency across > > the util-linux manual pages. > > > > As an example, there's quite a bit of variation in the order of > > .SH sections in the manual pages (e.g., in the placement of the SEE > > ALSO section). The pages would be more readable if the ordering was > > more consistent. > > > > Would you entertain patches that made wide-ranging changes > > that fixed that sort of thing (without changing page content? > > No problem, Ok. > but it would be nice to somehow document that is expected > to avoid future changes in an opposite way. For example add some info > to Documentation/howto-man-page.txt. Agreed. For man-pages, I created man-pags(7) to document those expectations. At least some of that should be applicable in othe pojects, if they want. > BTW, I'm not sure about man pages as ideal format to maintain > documentation (because it's mostly about formatting than about > content). I think about AsciiDoc or so in future. What do you think > about this idea? I'm not too knowledgeable in AsciiDc, but my impression is that it's too limited in terms of its formatting opinions. If I did move man-pages, the most likely candidate would probably be Sphinx, as is nowadays used in the kernel docs. But, that would require converting a thousand pages or so, and I have not so far had the stomach for that. Of course, you have a rather smaller set of pages to deal with, so a conversion step sould be more easily entertained. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Consistency fixes in util-linux man pages 2020-05-18 10:36 ` Michael Kerrisk (man-pages) @ 2020-05-18 15:03 ` Helge Kreutzmann 2020-05-19 10:38 ` Karel Zak 0 siblings, 1 reply; 6+ messages in thread From: Helge Kreutzmann @ 2020-05-18 15:03 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: Karel Zak, util-linux [-- Attachment #1: Type: text/plain, Size: 1711 bytes --] Hello Michael and Karel, On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote: > On Mon, 18 May 2020 at 10:28, Karel Zak <kzak@redhat.com> wrote: > > BTW, I'm not sure about man pages as ideal format to maintain > > documentation (because it's mostly about formatting than about > > content). I think about AsciiDoc or so in future. What do you think > > about this idea? > > I'm not too knowledgeable in AsciiDc, but my impression is that it's > too limited in terms of its formatting opinions. > > If I did move man-pages, the most likely candidate would probably be > Sphinx, as is nowadays used in the kernel docs. But, that would > require converting a thousand pages or so, and I have not so far had > the stomach for that. Of course, you have a rather smaller set of > pages to deal with, so a conversion step sould be more easily > entertained. Even though man pages are limitted in formatting, they are universally available and, from our POV, getting more attention from the translators side. We just welcomed our seventh language. Probably not relevant for kenel side docs, but for programs by non programmers (and presumably non native speakers) man pages are good option. (Of course, translation tools for other formats exists and e.g. po4a supports many formats, it also need a dedicated community of translators). Greetings Helge -- Dr. Helge Kreutzmann debian@helgefjell.de Dipl.-Phys. http://www.helgefjell.de/debian.php 64bit GNU powered gpg signed mail preferred Help keep free software "libre": http://www.ffii.de/ [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Consistency fixes in util-linux man pages 2020-05-18 15:03 ` Helge Kreutzmann @ 2020-05-19 10:38 ` Karel Zak 2020-05-19 17:23 ` Helge Kreutzmann 0 siblings, 1 reply; 6+ messages in thread From: Karel Zak @ 2020-05-19 10:38 UTC (permalink / raw) To: Helge Kreutzmann; +Cc: Michael Kerrisk (man-pages), util-linux On Mon, May 18, 2020 at 05:03:13PM +0200, Helge Kreutzmann wrote: > On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote: > > I'm not too knowledgeable in AsciiDc, but my impression is that it's > > too limited in terms of its formatting opinions. Yes, I'm not sure about AsciiDoc limitations. For example systemd guys uses DocBook which is probably ultimate solution. > > > > If I did move man-pages, the most likely candidate would probably be > > Sphinx, as is nowadays used in the kernel docs. But, that would > > require converting a thousand pages or so, and I have not so far had > > the stomach for that. Of course, you have a rather smaller set of > > pages to deal with, so a conversion step sould be more easily > > entertained. > > Even though man pages are limitted in formatting, they are universally > available and, from our POV, getting more attention from the > translators side. We just welcomed our seventh language. Probably not > relevant for kenel side docs, but for programs by non programmers (and > presumably non native speakers) man pages are good option. The idea is maintain documentation (in git tree) in some content oriented language and then generate man pages from this content. It means in the official release tarball will be man pages and end-users will not see any difference. The issue I have with man pages is that contributor very often send patches to change formatting details and keep it consistent, avoid color-of-bike-shed discussions is very difficult. It would be better care about content and keep all the formatting details in some conversion template. Karel -- Karel Zak <kzak@redhat.com> http://karelzak.blogspot.com ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Consistency fixes in util-linux man pages 2020-05-19 10:38 ` Karel Zak @ 2020-05-19 17:23 ` Helge Kreutzmann 0 siblings, 0 replies; 6+ messages in thread From: Helge Kreutzmann @ 2020-05-19 17:23 UTC (permalink / raw) To: Karel Zak; +Cc: Michael Kerrisk (man-pages), util-linux [-- Attachment #1: Type: text/plain, Size: 2546 bytes --] Hello Karel, On Tue, May 19, 2020 at 12:38:32PM +0200, Karel Zak wrote: > On Mon, May 18, 2020 at 05:03:13PM +0200, Helge Kreutzmann wrote: > > On Mon, May 18, 2020 at 12:36:01PM +0200, Michael Kerrisk (man-pages) wrote: > > > I'm not too knowledgeable in AsciiDc, but my impression is that it's > > > too limited in terms of its formatting opinions. > > Yes, I'm not sure about AsciiDoc limitations. For example systemd guys uses > DocBook which is probably ultimate solution. I'm currently translating them. Also I've used DocBook myself to write manges (a long time ago). > > > If I did move man-pages, the most likely candidate would probably be > > > Sphinx, as is nowadays used in the kernel docs. But, that would > > > require converting a thousand pages or so, and I have not so far had > > > the stomach for that. Of course, you have a rather smaller set of > > > pages to deal with, so a conversion step sould be more easily > > > entertained. > > > > Even though man pages are limitted in formatting, they are universally > > available and, from our POV, getting more attention from the > > translators side. We just welcomed our seventh language. Probably not > > relevant for kenel side docs, but for programs by non programmers (and > > presumably non native speakers) man pages are good option. > > The idea is maintain documentation (in git tree) in some content > oriented language and then generate man pages from this content. It > means in the official release tarball will be man pages and end-users > will not see any difference. Ok, then this is fine. > The issue I have with man pages is that contributor very often send > patches to change formatting details and keep it consistent, avoid > color-of-bike-shed discussions is very difficult. It would be better > care about content and keep all the formatting details in some > conversion template. I strongly agree. Keep content and presentation separate. This also helps us translators, even though we don't see the original markup, we do quickly understand the results, because it is consistent, i.e. what to translate and what to leave untranslated (e.g. command names vs. variable names) Greetings Helge -- Dr. Helge Kreutzmann debian@helgefjell.de Dipl.-Phys. http://www.helgefjell.de/debian.php 64bit GNU powered gpg signed mail preferred Help keep free software "libre": http://www.ffii.de/ [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-05-19 17:23 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-05-16 8:24 Consistency fixes in util-linux man pages Michael Kerrisk (man-pages) 2020-05-18 8:28 ` Karel Zak 2020-05-18 10:36 ` Michael Kerrisk (man-pages) 2020-05-18 15:03 ` Helge Kreutzmann 2020-05-19 10:38 ` Karel Zak 2020-05-19 17:23 ` Helge Kreutzmann
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).