Am 14.07.2016 um 20:02 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:
> 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.
OK
>>>> 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.
unanimous .. this is what I wanted to express ;-)
>> 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.
OK, if row AND cell spanning is to hard, I reduced first to cell spanning.
> 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.
The method I linked is only the visitor for a table cell. There is also
a "depart_entry" method where the context is popped up and added to the
table content.
A translation is done by traversing the node-tree. The Translator has
visit and depart handles for every node (-class) on the node tree:
def visit_table(self, node): # think about a XML start tag <table>
self._active_table = Table()
Some node classes (inline markup like "*bold*") are trivial, other nodes
classes (block markup like tables) are more complex.
E.g.: The sum of all nodes between the table-start and table-end is the
content of the table and all visitor and depart handles of theses nodes
only gathering the content of the table. The Table is build when the table
node is fully traversed:
def depart_table(self, node): # think about a XML end tag </table>
self.ensure_eol()
self.body.extend(self._active_table.as_list()) # this builds/outputs the table
self._active_table = None
The "Table()" class is defined here:
https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/manpage.py#L111
There you find the "def as_list(self,)" method which does all the stuff
you have been looking for.
Saying this, internally, the reST markup has a node structure which is very
similarly to what you know from XML, only the markup is less verbosely :-)
And if you implement a directive, you implement something what is generating
a node structure. E.g the flat-table directive generates a common node tree
of a table like you do with ascii art table or with the list-table directive.
The node tree is every time the same, containing rows and cells.
-- Markus --
--
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
