Em Thu, 14 Jul 2016 17:41:47 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> Am 14.07.2016 um 16:19 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:
> > If we're willing to document single drivers (I'm now talking
> > only about kernel-docs), then having an AUTHOR could be interesting.
> >
> > Yet, IMHO, the best would be, instead, to look into the MAINTAINERS
> > file and get the emails of the ones responsible for maintaining the
> > driver (usually a mailing list), using a logic similar to:
> > ./scripts/get_maintainers.pl
>
> May I misunderstood you: how should this work? ... I mean, the
> reST file is somewhere under Documentation/ ... this might work
> for kernel-doc generated man pages, where the source file is parsed.
Yes, I'm talking about using it for kernel-doc processed man pages.
It could call get_maintainers.pl to retrieve just the entires at
MAINTAINERS.
> >> What are your suggestions about man page generation?
> >
> > One thing that it needs to address is that the flat-tables should
> > also be converted somehow to groff format. Groff has a table
> > preprocessor (tbl). With that, outputting some thing like:
> >
> > .TS
> > tab(;) allbox;
> > l l
> > l ld
> > r ^
> > l rd.
> > 0000;foobar
> > T{
> > 1111
> > .br
> > 2222
> > T};foo
> > r;
> > T{
> > 3333
> > .br
> > 4444
> > T};bar
> > \^;\^
> > .TE
> >
> > (example copied from tbl man page)
> >
> > will produce this table with:
> >
> > $ man ./foo
> >
> > ┌─────┬────────┐
> > │0000 │ foobar │
> > ├─────┼────────┤
> > │1111 │ │
> > │2222 │ │
> > ├─────┤ │
> > │ r │ foo │
> > ├─────┼────────┤
> > │3333 │ │
> > │4444 │ bar │
> > └─────┴────────┘
> >
> > Yet, I'm not sure how portable is to use such preprocessor.
>
> About portability, the tbl man page says:
>
> The output generated by GNU tbl cannot
> be processed with Unix troff; it must be
> processed with GNU troff.
Yes, I know, but I suspect that the original Unix troff has
long gone on Linux distributions.
> About reST tables:
>
> The output of tables is independent from the reST markup you
> used to describe the table ... ASCII art tables and flat-tables
> result in the same (internal) node-tree. So it does not matter
> if you define a cell spanning with ASCII art or with the
> flat-table directive.
That's good news.
> The problem is, that the underlying man page translator does not
> support row or cell spanning:
>
> https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/manpage.py#L615
I see.
> I think I could extend the Translator to support row and
> cell spanning, but as far as I can estimate from here, this
> this will need some efforts.
I'm almost sure we don't use row spanning. Not sure how many
pages use cell spanning among the ones that describe ioctls,
but I guess that at least cell spanning would be required.
Btw, I'm a not python programmer, but it seems that even a
simple table will be badly formatted, as it seems that it
only adds the text document without actually trying to convert
the table into something more readable... it seems the code
only does:
self.context.append(len(self.body))
I would be expecting it to add some tags, like using .TP,
in order to indent the table.
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
