Re: [nft PATCH RFC] Convert man page source to asciidoc

[Phil Sutter <phil@nwl.cc>]

On Wed, Sep 06, 2017 at 04:29:00PM +0200, Jan Engelhardt wrote:
> 
> On Wednesday 2017-09-06 16:02, Phil Sutter wrote:
> >> Knowing that, people just avoid them most of the time for groff - and if I may
> >> say so, it has not reduced the document quality.
> >
> >Right now, nft.8 makes extensive use of tables which is why I considered
> >proper table support an important feature. OTOH I didn't experience
> >rendering issues with them in nft.8, did you?
> 
> I do. For some reason, the right margin of the table is 60% of the
> terminal width. (width 120 => table up to col #63, terminal 80 cols
> => table up to col #50).

Oh, I see that too, also in my asciidoc PoC. Explicitly setting the
table width to 100% doesn't help either. Maybe this is a problem in
groff? The tables span the whole page in asciidoc's PDF output at least.

[...]
> However, what I tried to express is the problem with tables is that
> one column has almost no text and another has a lot of it, like this
> one. This causes large amounts of whitespace in column 1 in this
> case. Personally, I would have placed the hooks and their
> explanations as (the equivalent of)
> 
> .TP
> \fBprerouting\fP
> All packets enter ...
> .TP
> \fBinput\fP
> Packets delivered ...
> 
> Or if the source material was HTML, perhaps just
> 
> <ul>
> <li><b>prerouting</b>: All packets enter...</li>
> <li><b>input</b>: Packets delivered...</li>
> </ul>

Yes, we should indeed convert two-column tables to these labeled lists
if they are merely keyword descriptions. I'm not sure about other cases,
sometimes having the table headings allows to provide information in a
more compact form than embedding everything into a paragraph of text.

[...]
> In another way, I could also ask why hooks are in tables, and commands 
> ("add", "flush", etc.) are in TP-style. What makes hooks so special that 
> they deserve a table, despite their keyword being the same short length 
> as the commands.

Many of the tables seem to be there for reasons of document structure,
e.g. those below DATA TYPES. I don't think that is a bad thing per se.

> >> >> There are many markup languages, it reminds me to xkcd #927 [0].
> >> >
> >> >Well, the difference here is that I'm not inventing anything new but
> >> >search for better options amongst the existing solutions. :P
> >> 
> >> That would be to stay with docbook then, because RST/MD/A2 do not seem to have
> >> left themselves a lot of room for later extension.
> >
> >What extensions do you have in mind?
> 
> I kind of left that open; it seemed you implied there is something
> (the "better option") that MD couldn't do that asciidoc could. That
> thing, docbook should already have.

I think docbook is the most "feature complete" solution amongst those
mentioned. My personal motivation to replace it is basically founded by
two things:

1) XML is not quite editor-friendly. I found myself spending way more
   time opening and closing tags than I had anticipated for whenever I
   worked on content.

2) I didn't like how docbook formats synopfragment/synopfragmentref
   constructs. Maybe this could be changed by using some customization
   though. Also I didn't see an equivalent to it in asciidoc - BNF-style
   referencing is done manually there.

Cheers, Phil