"G. Branden Robinson" <[email protected]> wrote: |At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote: ... |I entirely agree with the virtues of semantic of "presentation"-based |markup. However, this could be mitigated by encouraging a consistent |style in groff_man(7) itself. Some coordination with Michael Kerrisk et
I don't think this will work. Only in an ideal work. |al. of the man-pages project would be valuable as well; I think almost |all of the advice in man-pages(7) of that package is very sound. I think at least the structural information guidelines should somehow end up in the roff_man(7) that ships with roff in the end, it would mirror what there is roff_mdoc(7). ... |People keeep writing in man(7). Let's do what we can to help them write |it better. |I submit that one reason mdoc didn't take over the world is for the same |reason DocBook didn't--it's too huge. I think that man(7), even with |the an-ext stuff added on, is small enough to keep in one's head. ... |Of course what we need is a converter that goes in the other direction; |but that requires the encoding of semantic information that is lacking. Self-describing macro names may be helpful. In my opinion mdoc is gross and terrible, and you cannot even use it to document C code very nicely. But it has semantic information and that is necessary for good manuals in a generic language; you can very well create your own macros and process them with scripts and tools to create the necessary environment, but that is not generic. Currently i think the future is some rich-text thing like asciidoc or similar, and what would be needed would be good converters to roff, and then mdoc not man, because it keeps at least a bit of semantic information. Or a completely new roff manual language. I for one keep being disappointed when i see how much work is put into books and articles, with footnotes, TOC, index, etc. It would be nice if you could run mandb and get a real book, cross- referenced, with index, even better than what texinfo is or was. |I'd like to see what we can achieve by fiddling with it _without_ |harming its portability. Even as small as man(7) is, people neglect a |lot of its capabilities. Yes, i think people mostly do it by copying over and/or looking into manual pages they think look good, rather than by reading the manual, or bying a good tutorial book that leads them step-by-step, but fast!, to good results. That is the material world baby, you want the burger royal with fifteen, whereas a Ayurveda masseur has to sit beside his master and wait for i think seven years before he gets his hands at the subject. --steffen
