Hello Karel, On Mon, 18 May 2020 at 10:28, Karel Zak <kzak@xxxxxxxxxx> 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/
