Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1333371 > unrolled thread

Kernel docs: muddying the waters a bit

Back to article view | Back to linux.kernel

Contents

  Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-13 23:00 +0100
    Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-14 02:00 +0100
      Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-14 13:30 +0100
        Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-14 17:30 +0100
        Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-17 23:20 +0100
          Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-17 23:30 +0100
            Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-18 10:20 +0100
              Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-18 10:30 +0100
                Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 11:30 +0100
                  Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-18 12:30 +0100
                    Re: Kernel docs: muddying the waters a bit Hans Verkuil <hverkuil@xs4all.nl> - 2016-02-18 13:10 +0100
                      Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 13:50 +0100
                        Re: Kernel docs: muddying the waters a bit Patrick Boettcher <patrick.boettcher@posteo.de> - 2016-02-18 14:40 +0100
                    Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-02-18 13:10 +0100
                Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-18 14:10 +0100
                  Re: Kernel docs: muddying the waters a bit Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-02-18 15:50 +0100
    Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-16 09:30 +0100
      Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-16 17:10 +0100
        Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-02-16 18:20 +0100
      Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-16 20:20 +0100
        Re: Kernel docs: muddying the waters a bit Jonathan Corbet <corbet@lwn.net> - 2016-02-16 21:00 +0100
          Re: Kernel docs: muddying the waters a bit Keith Packard <keithp@keithp.com> - 2016-02-17 01:10 +0100

Page 1 of 2  [1] 2  Next page →

#1333371 — Kernel docs: muddying the waters a bit

So I fear you all are going to hate me for this...

Asciidoc is a credible solution to the formatted documentation problem,
but it's not the only such; I'd like to be sure that we pick the right
one.  I worry that asciidoc seems to be aimed mostly at small documents,
and that the project itself seems a little lifeless - it's not a good
sign when your main page's link to the repository has been dead for a long
time.  (Asciidoctor seems more active, with the Github folks behind it,
but that means bringing Ruby into the picture).

An alternative we haven't really looked at yet is ReStructuredText (or
"RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
Sphinx is a fairly sophisticated documentation system that uses RST.

I spent a few hours reworking the asciidoc patches to do RST instead, then
built a few template files' worth of docs.  The result can be seen at:

	http://static.lwn.net/kerneldoc/

It's very much a POC (however you might want to define the term), there's
lots of glitches, I chose a theme pretty much at random, etc.  But it
shows that it can be done.

Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
requirements there.  It produces integrated, multi-file HTML natively,
with a TOC, an index, cross-file cross references, and more.  It can make
things like function indexes.  It claims output in epub, docbook, and man
(I've not yet messed with those).  The path to PDF is via latex; clearly
the docbook path could be used too.

I used my same docproc hack to extract the comments here, mostly because I
had it at hand.  We could go with Jani's separate-file approach if we
wanted.  There's also a tool out there (called "breathe") that's meant to
turn doxygen-style comments into RST; I haven't had a chance to mess with
it.  We *could* also write an extension to pull the comments directly in
Sphinx if there were a compelling reason to do so.

If anybody's curious, the work done to get this far is in:

	git://git.lwn.net/linux.git doc/sphinx

but it looks suspiciously like the previous asciidoc patches, and, in any
case, it would have to be thrown out, publicly disowned, and replaced
before going any further with this, should that be what we decide to do.

So can we discuss?  I'm not saying we have to use Sphinx, but, should we
choose not to, we should do so with open eyes and good reasons for the
course we do take.  What do you all think?

jon

[toc] | [next] | [standalone]

#1333387

[Multipart message — attachments visible in raw view] — view raw

Jonathan Corbet <corbet@lwn.net> writes:

> Asciidoc is a credible solution to the formatted documentation problem,
> but it's not the only such; I'd like to be sure that we pick the right
> one.  I worry that asciidoc seems to be aimed mostly at small documents,
> and that the project itself seems a little lifeless - it's not a good
> sign when your main page's link to the repository has been dead for a long
> time.  (Asciidoctor seems more active, with the Github folks behind it,
> but that means bringing Ruby into the picture).

I was surprised when one of the asciidoctor developers said that
asciidoc itself was 'in maintenance mode for existing users'. I've tried
asciidoctor but never got it to the point where I was happy with the
results. Having two tools using the same nominal format doesn't seem
like a great idea to me.

It's also clear from my hacking in asciidoc that docbook is the expected
target for that tool. I've managed to make direct HTML output usable,
but LaTeX doesn't work at all. Something which focuses on direct HTML
(and ePub) output would be pretty nice.

> An alternative we haven't really looked at yet is ReStructuredText (or
> "RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
> YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
> Sphinx is a fairly sophisticated documentation system that uses RST.

I've installed debian's python3-sphinx package; it looks like it doesn't
have a huge dependency chain below it, which is a nice change.

I translated a fairly long document from asciidoc to rst using pandoc by
using the docbook output from asciidoc -- pandoc doesn't have a native
asciidoc reader, only a writer. The result didn't totally suck, although
I haven't messed with fixing the css or using a different theme at all.

http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html

I installed the sphinxcontrib.fulltoc extension so that the whole TOC
was visible from each section; this made navigating a lot easier. Having
search included (if you have javascript) seems like a nice feature.

> Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
> requirements there.

Having functional native latex output means that even PDF generation is
lighterweight though.

> It produces integrated, multi-file HTML natively,
> with a TOC, an index, cross-file cross references, and more.  It can make
> things like function indexes.  It claims output in epub, docbook, and man
> (I've not yet messed with those).  The path to PDF is via latex; clearly
> the docbook path could be used too.

I've tried epub and latex backends; epub seems just fine (it's just
html, after all). LaTeX works, and generates functional PDF, but I'm
going to have to spend a bunch of time making it looks nice.

http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf

> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
> choose not to, we should do so with open eyes and good reasons for the
> course we do take.  What do you all think?

Having spent the afternoon playing with it, I'm definitely
impressed. I've spent a ton of time getting asciidoc to generate html
and pdf that I can tolerate; far too much of that involved hacking XML
files related to the docbook backend.

Pros

 * Credible HTML output without docbook

 * Credible PDF output without docbook.

 * Constructs a unified set of documents across
   multiple files.

 * Written in Python (2 or 3)

 * PanDoc already supports rst for both input and output. So, if we get
   bored with RST, we've got a way out.

Cons

 * Table formatting doesn't seem as sophisticated as asciidoc

Questions

 * Conditional text appears to be harder to manage (I haven't managed to
   make it work at all).

 * Takes over a directory making building more than one
   document in a directory hard/impossible? The config file must be
   named 'conf.py'?
   
-- 
-keith

[toc] | [prev] | [next] | [standalone]

#1333496

On Sun, Feb 14, 2016 at 1:57 AM, Keith Packard <keithp@keithp.com> wrote:
> Jonathan Corbet <corbet@lwn.net> writes:
>
>> Asciidoc is a credible solution to the formatted documentation problem,
>> but it's not the only such; I'd like to be sure that we pick the right
>> one.  I worry that asciidoc seems to be aimed mostly at small documents,
>> and that the project itself seems a little lifeless - it's not a good
>> sign when your main page's link to the repository has been dead for a long
>> time.  (Asciidoctor seems more active, with the Github folks behind it,
>> but that means bringing Ruby into the picture).
>
> I was surprised when one of the asciidoctor developers said that
> asciidoc itself was 'in maintenance mode for existing users'. I've tried
> asciidoctor but never got it to the point where I was happy with the
> results. Having two tools using the same nominal format doesn't seem
> like a great idea to me.
>
> It's also clear from my hacking in asciidoc that docbook is the expected
> target for that tool. I've managed to make direct HTML output usable,
> but LaTeX doesn't work at all. Something which focuses on direct HTML
> (and ePub) output would be pretty nice.
>
>> An alternative we haven't really looked at yet is ReStructuredText (or
>> "RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
>> YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
>> Sphinx is a fairly sophisticated documentation system that uses RST.
>
> I've installed debian's python3-sphinx package; it looks like it doesn't
> have a huge dependency chain below it, which is a nice change.
>
> I translated a fairly long document from asciidoc to rst using pandoc by
> using the docbook output from asciidoc -- pandoc doesn't have a native
> asciidoc reader, only a writer. The result didn't totally suck, although
> I haven't messed with fixing the css or using a different theme at all.
>
> http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html
>
> I installed the sphinxcontrib.fulltoc extension so that the whole TOC
> was visible from each section; this made navigating a lot easier. Having
> search included (if you have javascript) seems like a nice feature.
>
>> Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
>> requirements there.
>
> Having functional native latex output means that even PDF generation is
> lighterweight though.
>
>> It produces integrated, multi-file HTML natively,
>> with a TOC, an index, cross-file cross references, and more.  It can make
>> things like function indexes.  It claims output in epub, docbook, and man
>> (I've not yet messed with those).  The path to PDF is via latex; clearly
>> the docbook path could be used too.
>
> I've tried epub and latex backends; epub seems just fine (it's just
> html, after all). LaTeX works, and generates functional PDF, but I'm
> going to have to spend a bunch of time making it looks nice.
>
> http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf
>
>> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
>> choose not to, we should do so with open eyes and good reasons for the
>> course we do take.  What do you all think?
>
> Having spent the afternoon playing with it, I'm definitely
> impressed. I've spent a ton of time getting asciidoc to generate html
> and pdf that I can tolerate; far too much of that involved hacking XML
> files related to the docbook backend.
>
> Pros
>
>  * Credible HTML output without docbook
>
>  * Credible PDF output without docbook.
>
>  * Constructs a unified set of documents across
>    multiple files.
>
>  * Written in Python (2 or 3)
>
>  * PanDoc already supports rst for both input and output. So, if we get
>    bored with RST, we've got a way out.
>
> Cons
>
>  * Table formatting doesn't seem as sophisticated as asciidoc
>
> Questions
>
>  * Conditional text appears to be harder to manage (I haven't managed to
>    make it work at all).
>
>  * Takes over a directory making building more than one
>    document in a directory hard/impossible? The config file must be
>    named 'conf.py'?

One concern/open I have for pro/cons are the hyperlinks from kerneldoc
comments. Currently we have the postproc hack, iirc Jani's patches
generated links native when extracting the kerneldoc. What's the
solution with spinx?

The other one is graphs - Keith showed me some neat stuff that
asciidoc can do, and I definitely wanted to integrate something like
that as a follow-up into the kerneldoc toolchain. Often a diagram is a
lot more helpful than lots of words. Can sphinx gives us that too?

Wrt reformatting: I'm not going to like it, but I hope that with a bit
of sed we can fix up any of the asciidoc comments we have already
easily - right now we don't (yet) use much of the more sophisticated
markup yet. So much better to change now than 1 year down the road.

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1333515

[Multipart message — attachments visible in raw view] — view raw

Daniel Vetter <daniel.vetter@ffwll.ch> writes:

> The other one is graphs - Keith showed me some neat stuff that
> asciidoc can do, and I definitely wanted to integrate something like
> that as a follow-up into the kerneldoc toolchain. Often a diagram is a
> lot more helpful than lots of words. Can sphinx gives us that too?

.. graphviz::

   digraph foo {
	"bar" -> "baz";
   }

Even better than asciidoc -- svg output is supported in both html and
pdf (when using rst2pdf). I had to hack asciidoc to add support for svg
output when using docbook.

> Wrt reformatting: I'm not going to like it, but I hope that with a bit
> of sed we can fix up any of the asciidoc comments we have already
> easily - right now we don't (yet) use much of the more sophisticated
> markup yet. So much better to change now than 1 year down the road.

I used pandoc on the docbook output from asciidoc to get a 100 page
document converted here. It wasn't perfect -- all of the internal links
were busted, and labels for tables were mis-positioned. It might be that
a few minor fixes to pandoc could be done to add 'sphinx'-specific rst
support that could fix this?

I spent (too much) time yesterday playing with sphinx and generated a
new html theme. Here's the result:

        http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html

Here's the PDF output from rst2pdf, a python-based PDF output which
doesn't use docbook *or* latex:

        http://keithp.com/~keithp/altusmetrum-sphinx/Altus%20Metrum.pdf

I need to spend some quality time building my own PDF theme; the default
provided by rst2pdf isn't great. It does, however, use fontconfig, so
switching fonts is *way* easier than with docbook...

There's currently an incompatibility between the rst2pdf and sphnix
packages in debian (and upstream) which I hacked around to generate that
output, but otherwise I'm using packaged bits.

So, another pro for sphinx appears to be native PDF generation...

-- 
-keith

[toc] | [prev] | [next] | [standalone]

#1336812

On Sun, 14 Feb 2016 13:27:04 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> One concern/open I have for pro/cons are the hyperlinks from kerneldoc
> comments. Currently we have the postproc hack, iirc Jani's patches
> generated links native when extracting the kerneldoc. What's the
> solution with spinx?

So I've been trying to figure out what this refers to.  Is this the
cross-reference links within the document?  When I did my sphinx hack it
used a technique that, shall we say, strongly resembles what Jani's
patches did.  One difference is that Sphinx has the concept of
"functions" built into it, so I use function references for those.

If you mean links to the wider world, I'm not sure I see that in Jani's
patches.  It's going to be easily managed in whatever markup language we
use, though.

jon

[toc] | [prev] | [next] | [standalone]

#1336821

On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Sun, 14 Feb 2016 13:27:04 +0100
> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>
>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc
>> comments. Currently we have the postproc hack, iirc Jani's patches
>> generated links native when extracting the kerneldoc. What's the
>> solution with spinx?
>
> So I've been trying to figure out what this refers to.  Is this the
> cross-reference links within the document?  When I did my sphinx hack it
> used a technique that, shall we say, strongly resembles what Jani's
> patches did.  One difference is that Sphinx has the concept of
> "functions" built into it, so I use function references for those.

That's what I meant. As long as I can type in stuff like func(),
&struct and similar and get a link for it automatically (plus anywhere
else in the templated stuff for function headers) I'm really happy.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1337180

On Thu, 18 Feb 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet <corbet@lwn.net> wrote:
>> On Sun, 14 Feb 2016 13:27:04 +0100
>> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>>
>>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc
>>> comments. Currently we have the postproc hack, iirc Jani's patches
>>> generated links native when extracting the kerneldoc. What's the
>>> solution with spinx?
>>
>> So I've been trying to figure out what this refers to.  Is this the
>> cross-reference links within the document?  When I did my sphinx hack it
>> used a technique that, shall we say, strongly resembles what Jani's
>> patches did.  One difference is that Sphinx has the concept of
>> "functions" built into it, so I use function references for those.
>
> That's what I meant. As long as I can type in stuff like func(),
> &struct and similar and get a link for it automatically (plus anywhere
> else in the templated stuff for function headers) I'm really happy.

I think that could be made to work in rst just as well as
asciidoc. Which is to say, kernel-doc may generate broken refs in both,
since it doesn't know if the link target exists outside of the
file. Also, in theory, it's possible to generate non-unique targets in
the end result if there are same named enums, structs, static functions
etc. but I think that's less of a problem. Asciidoc just ignores these
issues, I don't know what sphinx does.

I think some of that could be alleviated by making the kernel-doc
inclusion a directive through a sphinx extension. It could at the very
least provide informative error messages. But that's distant future.

Worth noting is that, AFAICT, in all of the proposals, including the
original where kernel-doc produces docbook, this autoreferencing only
works within parts processed by kernel-doc. Not in the template
documents themselves. (You can still use the markup's more verbose cross
referencing keywords.)


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1337192

On Thu, Feb 18, 2016 at 10:11 AM, Jani Nikula <jani.nikula@intel.com> wrote:
> On Thu, 18 Feb 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet <corbet@lwn.net> wrote:
>>> On Sun, 14 Feb 2016 13:27:04 +0100
>>> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>>>
>>>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc
>>>> comments. Currently we have the postproc hack, iirc Jani's patches
>>>> generated links native when extracting the kerneldoc. What's the
>>>> solution with spinx?
>>>
>>> So I've been trying to figure out what this refers to.  Is this the
>>> cross-reference links within the document?  When I did my sphinx hack it
>>> used a technique that, shall we say, strongly resembles what Jani's
>>> patches did.  One difference is that Sphinx has the concept of
>>> "functions" built into it, so I use function references for those.
>>
>> That's what I meant. As long as I can type in stuff like func(),
>> &struct and similar and get a link for it automatically (plus anywhere
>> else in the templated stuff for function headers) I'm really happy.
>
> I think that could be made to work in rst just as well as
> asciidoc. Which is to say, kernel-doc may generate broken refs in both,
> since it doesn't know if the link target exists outside of the
> file. Also, in theory, it's possible to generate non-unique targets in
> the end result if there are same named enums, structs, static functions
> etc. but I think that's less of a problem. Asciidoc just ignores these
> issues, I don't know what sphinx does.
>
> I think some of that could be alleviated by making the kernel-doc
> inclusion a directive through a sphinx extension. It could at the very
> least provide informative error messages. But that's distant future.
>
> Worth noting is that, AFAICT, in all of the proposals, including the
> original where kernel-doc produces docbook, this autoreferencing only
> works within parts processed by kernel-doc. Not in the template
> documents themselves. (You can still use the markup's more verbose cross
> referencing keywords.)

It works everywhere, even in the docbook template, as long as you mark
it up correctly. Which in docbook means <function>func</function>.
That's because it's a post-proc path over the entire doc. But then the
entire point here is to move the overview sections all into kerneldoc,
so making the links in the templates more verbose shouldn't be a big
deal.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1337232

Em Thu, 18 Feb 2016 10:24:04 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> escreveu:

> On Thu, Feb 18, 2016 at 10:11 AM, Jani Nikula <jani.nikula@intel.com> wrote:
> > On Thu, 18 Feb 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:  
> >> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet <corbet@lwn.net> wrote:  
> >>> On Sun, 14 Feb 2016 13:27:04 +0100
> >>> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> >>>  
> >>>> One concern/open I have for pro/cons are the hyperlinks from kerneldoc
> >>>> comments. Currently we have the postproc hack, iirc Jani's patches
> >>>> generated links native when extracting the kerneldoc. What's the
> >>>> solution with spinx?  
> >>>
> >>> So I've been trying to figure out what this refers to.  Is this the
> >>> cross-reference links within the document?  When I did my sphinx hack it
> >>> used a technique that, shall we say, strongly resembles what Jani's
> >>> patches did.  One difference is that Sphinx has the concept of
> >>> "functions" built into it, so I use function references for those.  
> >>
> >> That's what I meant. As long as I can type in stuff like func(),
> >> &struct and similar and get a link for it automatically (plus anywhere
> >> else in the templated stuff for function headers) I'm really happy.  
> >
> > I think that could be made to work in rst just as well as
> > asciidoc. Which is to say, kernel-doc may generate broken refs in both,
> > since it doesn't know if the link target exists outside of the
> > file. Also, in theory, it's possible to generate non-unique targets in
> > the end result if there are same named enums, structs, static functions
> > etc. but I think that's less of a problem. Asciidoc just ignores these
> > issues, I don't know what sphinx does.
> >
> > I think some of that could be alleviated by making the kernel-doc
> > inclusion a directive through a sphinx extension. It could at the very
> > least provide informative error messages. But that's distant future.
> >
> > Worth noting is that, AFAICT, in all of the proposals, including the
> > original where kernel-doc produces docbook, this autoreferencing only
> > works within parts processed by kernel-doc. Not in the template
> > documents themselves. (You can still use the markup's more verbose cross
> > referencing keywords.)  
> 
> It works everywhere, even in the docbook template, as long as you mark
> it up correctly. Which in docbook means <function>func</function>.
> That's because it's a post-proc path over the entire doc. But then the
> entire point here is to move the overview sections all into kerneldoc,
> so making the links in the templates more verbose shouldn't be a big
> deal.

For simple documents like the one produced by kernel-doc, I guess
all markup languages would work equally.

The problem is for complex documents like the media kAPI one, where
the document was written to produce a book. So, it uses some complex
features found at DocBook. One of such features we use extensively
is the capability of having a table with per-line columns. This way,
we can produce things like:

V4L2_CID_COLOR_KILLER	boolean	Enable the color killer (i. e. force a black & white image in case of a weak video signal).
V4L2_CID_COLORFX	enum	Selects a color effect. The following values are defined:
				V4L2_COLORFX_NONE 		Color effect is disabled.
				V4L2_COLORFX_ANTIQUE 		An aging (old photo) effect.
				V4L2_COLORFX_ART_FREEZE 	Frost color effect.

In the above example, we have a main 3 columns table, and we embed
a 2 columns table at the third field of V4L2_CID_COLORFX to represent
possible values for this menu control.

See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
complete output of it.

This is used extensively inside the media DocBook, and properly
supporting it is one of our major concerns.

Are there any way to represent those things with the markup
languages currently being analyzed?

Converting those tables will likely require manual work, as I don't
think automatic tools will properly handle it, specially since we
use some DocBook macros to help creating such tables.

-- 
Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1337285

On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> For simple documents like the one produced by kernel-doc, I guess
> all markup languages would work equally.
>
> The problem is for complex documents like the media kAPI one, where
> the document was written to produce a book. So, it uses some complex
> features found at DocBook. One of such features we use extensively
> is the capability of having a table with per-line columns. This way,
> we can produce things like:
>
> V4L2_CID_COLOR_KILLER	boolean	Enable the color killer (i. e. force a black & white image in case of a weak video signal).
> V4L2_CID_COLORFX	enum	Selects a color effect. The following values are defined:
> 				V4L2_COLORFX_NONE 		Color effect is disabled.
> 				V4L2_COLORFX_ANTIQUE 		An aging (old photo) effect.
> 				V4L2_COLORFX_ART_FREEZE 	Frost color effect.
>
> In the above example, we have a main 3 columns table, and we embed
> a 2 columns table at the third field of V4L2_CID_COLORFX to represent
> possible values for this menu control.
>
> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
> complete output of it.
>
> This is used extensively inside the media DocBook, and properly
> supporting it is one of our major concerns.
>
> Are there any way to represent those things with the markup
> languages currently being analyzed?
>
> Converting those tables will likely require manual work, as I don't
> think automatic tools will properly handle it, specially since we
> use some DocBook macros to help creating such tables.

Since I've let myself be told that asciidoc handles tables better than
reStructuredText, I tested this a bit with the presumably inferior one.

rst has two table types, simple tables and grid tables [1]. It seems
like grid tables can do pretty much anything, but they can be cumbersome
to work with. So I tried to check what can be done with simple tables.

Here's a sample, converted using rst2html (Sphinx will be prettier, but
rst2html works for simple things like this):

https://people.freedesktop.org/~jani/v4l-table-within-table.rst
https://people.freedesktop.org/~jani/v4l-table-within-table.html

Rather than using nested tables, you might want to consider using
definition lists within tables:

https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst
https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html

You be the judge, but I think this is workable.

BR,
Jani.


[1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1337302

On 02/18/16 13:04, Mauro Carvalho Chehab wrote:
> Em Thu, 18 Feb 2016 13:23:37 +0200
> Jani Nikula <jani.nikula@intel.com> escreveu:
> 
>> On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
>>> For simple documents like the one produced by kernel-doc, I guess
>>> all markup languages would work equally.
>>>
>>> The problem is for complex documents like the media kAPI one, where
>>> the document was written to produce a book. So, it uses some complex
>>> features found at DocBook. One of such features we use extensively
>>> is the capability of having a table with per-line columns. This way,
>>> we can produce things like:
>>>
>>> V4L2_CID_COLOR_KILLER	boolean	Enable the color killer (i. e. force a black & white image in case of a weak video signal).
>>> V4L2_CID_COLORFX	enum	Selects a color effect. The following values are defined:
>>> 				V4L2_COLORFX_NONE 		Color effect is disabled.
>>> 				V4L2_COLORFX_ANTIQUE 		An aging (old photo) effect.
>>> 				V4L2_COLORFX_ART_FREEZE 	Frost color effect.
>>>
>>> In the above example, we have a main 3 columns table, and we embed
>>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent
>>> possible values for this menu control.
>>>
>>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
>>> complete output of it.
>>>
>>> This is used extensively inside the media DocBook, and properly
>>> supporting it is one of our major concerns.
>>>
>>> Are there any way to represent those things with the markup
>>> languages currently being analyzed?
>>>
>>> Converting those tables will likely require manual work, as I don't
>>> think automatic tools will properly handle it, specially since we
>>> use some DocBook macros to help creating such tables.  
>>
>> Since I've let myself be told that asciidoc handles tables better than
>> reStructuredText, I tested this a bit with the presumably inferior one.
>>
>> rst has two table types, simple tables and grid tables [1]. It seems
>> like grid tables can do pretty much anything, but they can be cumbersome
>> to work with. So I tried to check what can be done with simple tables.
>>
>> Here's a sample, converted using rst2html (Sphinx will be prettier, but
>> rst2html works for simple things like this):
>>
>> https://people.freedesktop.org/~jani/v4l-table-within-table.rst
>> https://people.freedesktop.org/~jani/v4l-table-within-table.html
> 
> Yes, this would work. Can we remove the border from the main table?
> I guess it would be nicer.
> 
>>
>> Rather than using nested tables, you might want to consider using
>> definition lists within tables:
>>
>> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst
>> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html
>>
>> You be the judge, but I think this is workable.
> 
> It is workable, but I guess nested tables produced a better result.
> 
> I did myself a test with nested tables with asciidoc too:
> 
> https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html
> https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii
> 
> With looks very decent to me.

It does, except for the vertical alignment of the third column (at least when viewed
with google chrome).

	Hans

> 
> I had to manually add the nested table, as pandoc conversion sent the
> DocBook's nested table to /dev/null.
> 
> Thanks,
> Mauro
> 

[toc] | [prev] | [next] | [standalone]

#1337327

Em Thu, 18 Feb 2016 13:07:03 +0100
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 02/18/16 13:04, Mauro Carvalho Chehab wrote:
> > Em Thu, 18 Feb 2016 13:23:37 +0200
> > Jani Nikula <jani.nikula@intel.com> escreveu:
> >   
> >> On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:  
> >>> For simple documents like the one produced by kernel-doc, I guess
> >>> all markup languages would work equally.
> >>>
> >>> The problem is for complex documents like the media kAPI one, where
> >>> the document was written to produce a book. So, it uses some complex
> >>> features found at DocBook. One of such features we use extensively
> >>> is the capability of having a table with per-line columns. This way,
> >>> we can produce things like:
> >>>
> >>> V4L2_CID_COLOR_KILLER	boolean	Enable the color killer (i. e. force a black & white image in case of a weak video signal).
> >>> V4L2_CID_COLORFX	enum	Selects a color effect. The following values are defined:
> >>> 				V4L2_COLORFX_NONE 		Color effect is disabled.
> >>> 				V4L2_COLORFX_ANTIQUE 		An aging (old photo) effect.
> >>> 				V4L2_COLORFX_ART_FREEZE 	Frost color effect.
> >>>
> >>> In the above example, we have a main 3 columns table, and we embed
> >>> a 2 columns table at the third field of V4L2_CID_COLORFX to represent
> >>> possible values for this menu control.
> >>>
> >>> See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
> >>> complete output of it.
> >>>
> >>> This is used extensively inside the media DocBook, and properly
> >>> supporting it is one of our major concerns.
> >>>
> >>> Are there any way to represent those things with the markup
> >>> languages currently being analyzed?
> >>>
> >>> Converting those tables will likely require manual work, as I don't
> >>> think automatic tools will properly handle it, specially since we
> >>> use some DocBook macros to help creating such tables.    
> >>
> >> Since I've let myself be told that asciidoc handles tables better than
> >> reStructuredText, I tested this a bit with the presumably inferior one.
> >>
> >> rst has two table types, simple tables and grid tables [1]. It seems
> >> like grid tables can do pretty much anything, but they can be cumbersome
> >> to work with. So I tried to check what can be done with simple tables.
> >>
> >> Here's a sample, converted using rst2html (Sphinx will be prettier, but
> >> rst2html works for simple things like this):
> >>
> >> https://people.freedesktop.org/~jani/v4l-table-within-table.rst
> >> https://people.freedesktop.org/~jani/v4l-table-within-table.html  
> > 
> > Yes, this would work. Can we remove the border from the main table?
> > I guess it would be nicer.
> >   
> >>
> >> Rather than using nested tables, you might want to consider using
> >> definition lists within tables:
> >>
> >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst
> >> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html
> >>
> >> You be the judge, but I think this is workable.  
> > 
> > It is workable, but I guess nested tables produced a better result.
> > 
> > I did myself a test with nested tables with asciidoc too:
> > 
> > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html
> > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii
> > 
> > With looks very decent to me.  
> 
> It does, except for the vertical alignment of the third column (at least when viewed
> with google chrome).

Not sure what you mean. Here, it looks fine on both Firefox and Chrome,
except that the second colum size could be smaller. If this is what
you're meaning this can be fixed by changing the second line from:

	[width="100%",cols="2,1,10a",options="header",frame="none", grid="none"]

to:

	[width="100%",cols="3,1,30a",options="header",frame="none", grid="none"]

With regards to ReStructured Text, I've no idea how to control the
format of a table in order to do things like hiding the borders and
changing the column spacing.

So, at least on a first glance, asciidoc seems to fit better.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1337356

On Thu, 18 Feb 2016 10:44:34 -0200
Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> > > It is workable, but I guess nested tables produced a better
> > > result.
> > > 
> > > I did myself a test with nested tables with asciidoc too:
> > > 
> > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html
> > > https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii
> > > 
> > > With looks very decent to me.    
> > 
> > It does, except for the vertical alignment of the third column (at
> > least when viewed with google chrome).  
> 
> Not sure what you mean. Here, it looks fine on both Firefox and
> Chrome, except that the second colum size could be smaller. If this
> is what you're meaning this can be fixed by changing the second line
> from:

I think Hans' problem (I see it as well) is coming from css-style of
"paragraph" which is:

    margin-top: 0.5em;
    margin-bottom: 0.5em;

This makes the third column non-vertical-aligned

--
Patrick

[toc] | [prev] | [next] | [standalone]

#1337304

Em Thu, 18 Feb 2016 13:23:37 +0200
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Thu, 18 Feb 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> > For simple documents like the one produced by kernel-doc, I guess
> > all markup languages would work equally.
> >
> > The problem is for complex documents like the media kAPI one, where
> > the document was written to produce a book. So, it uses some complex
> > features found at DocBook. One of such features we use extensively
> > is the capability of having a table with per-line columns. This way,
> > we can produce things like:
> >
> > V4L2_CID_COLOR_KILLER	boolean	Enable the color killer (i. e. force a black & white image in case of a weak video signal).
> > V4L2_CID_COLORFX	enum	Selects a color effect. The following values are defined:
> > 				V4L2_COLORFX_NONE 		Color effect is disabled.
> > 				V4L2_COLORFX_ANTIQUE 		An aging (old photo) effect.
> > 				V4L2_COLORFX_ART_FREEZE 	Frost color effect.
> >
> > In the above example, we have a main 3 columns table, and we embed
> > a 2 columns table at the third field of V4L2_CID_COLORFX to represent
> > possible values for this menu control.
> >
> > See https://linuxtv.org/downloads/v4l-dvb-apis/control.html for the
> > complete output of it.
> >
> > This is used extensively inside the media DocBook, and properly
> > supporting it is one of our major concerns.
> >
> > Are there any way to represent those things with the markup
> > languages currently being analyzed?
> >
> > Converting those tables will likely require manual work, as I don't
> > think automatic tools will properly handle it, specially since we
> > use some DocBook macros to help creating such tables.  
> 
> Since I've let myself be told that asciidoc handles tables better than
> reStructuredText, I tested this a bit with the presumably inferior one.
> 
> rst has two table types, simple tables and grid tables [1]. It seems
> like grid tables can do pretty much anything, but they can be cumbersome
> to work with. So I tried to check what can be done with simple tables.
> 
> Here's a sample, converted using rst2html (Sphinx will be prettier, but
> rst2html works for simple things like this):
> 
> https://people.freedesktop.org/~jani/v4l-table-within-table.rst
> https://people.freedesktop.org/~jani/v4l-table-within-table.html

Yes, this would work. Can we remove the border from the main table?
I guess it would be nicer.

> 
> Rather than using nested tables, you might want to consider using
> definition lists within tables:
> 
> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.rst
> https://people.freedesktop.org/~jani/v4l-definition-list-within-table.html
> 
> You be the judge, but I think this is workable.

It is workable, but I guess nested tables produced a better result.

I did myself a test with nested tables with asciidoc too:

https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.html
https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/table.ascii

With looks very decent to me.

I had to manually add the nested table, as pandoc conversion sent the
DocBook's nested table to /dev/null.

Thanks,
Mauro

[toc] | [prev] | [next] | [standalone]

#1337338

On Thu, 18 Feb 2016 10:24:04 +0100
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> > Worth noting is that, AFAICT, in all of the proposals, including the
> > original where kernel-doc produces docbook, this autoreferencing only
> > works within parts processed by kernel-doc. Not in the template
> > documents themselves. (You can still use the markup's more verbose cross
> > referencing keywords.)  
> 
> It works everywhere, even in the docbook template, as long as you mark
> it up correctly. Which in docbook means <function>func</function>.

In Sphinx that's :func:`function_name`.  Not a thing of beauty, but it
works.

jon

[toc] | [prev] | [next] | [standalone]

#1337425

On Thu, Feb 18, 2016 at 2:01 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Thu, 18 Feb 2016 10:24:04 +0100
> Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>
>> > Worth noting is that, AFAICT, in all of the proposals, including the
>> > original where kernel-doc produces docbook, this autoreferencing only
>> > works within parts processed by kernel-doc. Not in the template
>> > documents themselves. (You can still use the markup's more verbose cross
>> > referencing keywords.)
>>
>> It works everywhere, even in the docbook template, as long as you mark
>> it up correctly. Which in docbook means <function>func</function>.
>
> In Sphinx that's :func:`function_name`.  Not a thing of beauty, but it
> works.

Compared to <function>function_name</function> already an improvement.
I can very much live with this ;-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

[toc] | [prev] | [next] | [standalone]

#1335133

On Sat, 13 Feb 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> So can we discuss?  I'm not saying we have to use Sphinx, but, should we
> choose not to, we should do so with open eyes and good reasons for the
> course we do take.  What do you all think?

FWIW I was in favor of reStructuredText to begin with, but decided I'd
rather have any lightweight markup than a bikeshed fest over which
one. Switching is a non-issue to me.

It does seem like the tools available for each markup carry more weight
than the markup itself, as long as there aren't any huge gaps. Sphinx
seems like a reasonable, actively developed choice.

However I didn't think Sphinx could produce docbook, and a quick search
doesn't convince me otherwise. Do you have some links to back this up?
Would the lack of docbook be a showstopper? (Of course, the pandoc
swiss-army knife can handle rst->docbook if needed.)

Sphinx might offer a way to drop docproc through the extension
mechanism, without resorting to the "separate-file approach". It might
be a more sensible approach as a whole.

I'll have a more in-depth look into this.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1335591

On Tue, 16 Feb 2016 10:25:49 +0200
Jani Nikula <jani.nikula@intel.com> wrote:

> However I didn't think Sphinx could produce docbook, and a quick search
> doesn't convince me otherwise. Do you have some links to back this up?

Somehow I was really sure of it, but I'm not finding it now.  There is an
extension out there, but it warns about being a "work in progress," so
I'm not sure we can count it.

Whether this is a show-stopper is indeed a good question.  I doubt many
people wanted the DocBook for its own sake, it's a matter of where you
can go from there.  But yes, it would be good to be sure on this point.

> Sphinx might offer a way to drop docproc through the extension
> mechanism, without resorting to the "separate-file approach". It might
> be a more sensible approach as a whole.

There's a certain elegance to it that I like, but it is an idea that
needs to actually be demonstrated.  It could also come later on, though,
with the docproc or include mechanisms used for now.

Thanks,

jon

[toc] | [prev] | [next] | [standalone]

#1335645

On Tue, 16 Feb 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> Whether this is a show-stopper is indeed a good question.  I doubt many
> people wanted the DocBook for its own sake, it's a matter of where you
> can go from there.  But yes, it would be good to be sure on this point.

So the question is, are HTML, latex (for pdf and presumably ps), epub,
texinfo, and man pages enough?

My subjective opinion is they are enough, and whoever wants more can
make it work for them using pandoc. It's not like we had this great
publishing framework before that we'd be breaking. Quite the opposite,
and it would be awesome to have a robust set of outputs actually working
for the majority of people.

> There's a certain elegance to it that I like, but it is an idea that
> needs to actually be demonstrated.  It could also come later on, though,
> with the docproc or include mechanisms used for now.

Oh, totally agreed, I was just musing on potential follow-up work.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

[toc] | [prev] | [next] | [standalone]

#1335736

[Multipart message — attachments visible in raw view] — view raw

Jani Nikula <jani.nikula@intel.com> writes:

> However I didn't think Sphinx could produce docbook, and a quick search
> doesn't convince me otherwise. Do you have some links to back this up?
> Would the lack of docbook be a showstopper? (Of course, the pandoc
> swiss-army knife can handle rst->docbook if needed.)

A quick search yields:

	https://github.com/HolgerPeters/sphinxcontrib-docbook

which appears to provide docbook output for sphinx, but I haven't tested
this at all.

Of course, docbook is just a means to an end -- the question should
probably be what final output formats are actually required and whether
the tools generate those in a reasonable fashion.

-- 
-keith

[toc] | [prev] | [next] | [standalone]

Page 1 of 2  [1] 2  Next page →

Back to top | Article view | linux.kernel

csiph-web