From: Markus Heiser <markus.heiser@darmarit.de>
To: Mauro Carvalho Chehab <mchehab@osg.samsung.com>,
Jani Nikula <jani.nikula@intel.com>,
Dan Allen <dan@opendevise.io>,
Russel Winder <russel@winder.org.uk>,
Keith Packard <keithp@keithp.com>,
Jonathan Corbet <corbet@lwn.net>,
LKML <linux-kernel@vger.kernel.org>,
"linux-doc@vger.kernel.org" <linux-doc@vger.kernel.org>,
Daniel Vetter <daniel.vetter@ffwll.ch>,
Hans Verkuil <hverkuil@xs4all.nl>,
"linux-media@vger.kernel.org linux-media"
<linux-media@vger.kernel.org>,
Graham Whaley <graham.whaley@linux.intel.com>
Subject: Re: Kernel docs: muddying the waters a bit
Date: Fri, 8 Apr 2016 17:12:27 +0200 [thread overview]
Message-ID: <8992F589-5B66-4BDB-807A-79AC8644F006@darmarit.de> (raw)
In-Reply-To: <AA8C4658-5361-4BE1-8A67-EB1C5F17C6B4@darmarit.de>
Hi kernel-doc authors,
motivated by this MT, I implemented a toolchain to migrate the kernel’s
DocBook XML documentation to reST markup.
It converts 99% of the docs well ... to gain an impression how
kernel-docs could benefit from, visit my sphkerneldoc project page
on github:
http://return42.github.io/sphkerneldoc/
The sources available at:
https://github.com/return42/sphkerneldoc
The work is underway, suggestions are welcome!
.. have a nice weekend ..
--M--
Am 13.03.2016 um 16:33 schrieb Markus Heiser <markus.heiser@darmarIT.de>:
>
> Am 10.03.2016 um 16:21 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:
>
>> Em Thu, 10 Mar 2016 12:25:58 +0200
>> Jani Nikula <jani.nikula@intel.com> escreveu:
>>
>>> TL;DR? Skip to the last paragraph.
>>>
>>> On Wed, 09 Mar 2016, Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
>>>> I guess the conversion to asciidoc format is now in good shape,
>>>> at least to demonstrate that it is possible to use this format for the
>>>> media docbook. Still, there are lots of broken references.
>>>
>>> Getting references right with asciidoc is a big problem in the
>>> kernel-doc side. As I wrote before, the proofs of concept only worked
>>> because everything was processed as one big file (via includes). The
>>> Asciidoctor inter-document references won't help, because we won't know
>>> the target document name while processing kernel-doc.
>>
>> I was able to produce chunked htmls here with:
>>
>> asciidoctor -b docbook45 media_api.adoc
>> xmlto -o html-dir html media_api.xml
>>
>> The results are at:
>> https://mchehab.fedorapeople.org/media-kabi-docs-test/asciidoc_tests/chunked/
>>
>> But yeah, all references seem to be broken there. It could be due to some
>> conversion issue (I didn't actually tried to check what's wrong there),
>> but I think that there's something not ok with docbook45
>> output for multi-part documents (on both AsciiDoc and Asciidoctor).
>>
>>> Sphinx is massively better at handling cross references for
>>> kernel-doc. We can use domains (C language) and roles (e.g. functions,
>>> types, etc.) for the references, which provide kind of
>>> namespaces. Sphinx warns for referencing non-existing targets, but
>>> doesn't generate broken links in the result like Asciidoctor does.
>>>
>>> For example, in the documentation for a function that has struct foo as
>>> parameter or return type, a cross reference to struct foo is added
>>> automagically, but only if documentation for struct foo actually
>>> exists. In Asciidoctor, we would have to blindly generate the references
>>> ourselves, and try to resolve broken links ourselves by somehow
>>> post-processing the result.
>>>
>>>> Yet, from my side, if we're willing to get rid of DocBook, then
>>>> Asciidoctor seems to be the *only* alternative so far to parse the
>>>> complex media documents.
>>>
>>> I think you mean, "get rid of DocBook as source format", not altogether?
>>> I'm yet to be convinved we could rely on Asciidoctor's native formats.
>>
>> What I mean is that, right now, I see only two alternatives for the
>> media uAPI documentation:
>> 1) keep using DocBook;
>> 2) AsciiDoc/Asciidoctor.
>>
>> Sphinx doesn't have what's needed to support the complexity of the
>> media books, specially since cell span seems to be possible only
>> by using asciiArt formats. Writing a big table using asciiArt is
>> something that is a *real pain*. Also, as tested, if the table is
>> too big, it fails to parse such asciiArt tables. So, while Sphinx
>> doesn't have a decent way to describe tables, we can't use it.
>
>
> Huge tables and cell-spans are the *real pain* ;-) ... with sphinx-doc,
> (mostly) you have more then one choice .. e.g. import csv tables ..
> but this should be discussed by example ...
>
>
>> If it starts implementing it, then we can check if the other
>> features used by the media documentation are also supported.
>> Probably, multi-part books would be another pain with Sphinx.
>> We have actually 4 books inside a common body. A few chapters
>> (like book licensing, bibliography, error codes) are shared
>> by all 4 documents.
>>
>> But, so far, I can't see any way to port media books without
>> lots of lot of work to develop new features at the Sphinx code.
>
>
> may I can help you ...
>
>
>>> The toolchain gets faster, easier to debug and simplified a lot with
>>> DocBook out of the equation completely. Sphinx itself is stable, widely
>>> available, and well documented. IMO there's sufficient native output
>>> format support. There are plenty of really nice extensions
>>> available. There's a possibility of doing kernel-doc as an extension in
>>> the future (either by calling current kernel-doc from the extension or
>>> by rewriting it).
>>
>> Well, if we go to Sphinx for kernel-doc, that means that we'll need
>> 2 different tools for the documentation:
>> - Sphinx for kernel-doc
>> - either DocBook or Asciidoctor/AsciiDoc for media.
>>
>> IMHO, this is the worse scenario, as we'll keep depending on
>> DocBook plus requiring Sphinx, but it is up to Jon to decide.
>>
>
> The migration of kernel-doc is a long term project, not a
> one shot job. The scope of documents to migrate is not limited
> to the files with DocBook markup in, most documents have not
> a real markup.
>
> Please take a look at my thoughts and efforts about migration.
>
> * https://sphkerneldoc.readthedocs.org
>
> * https://github.com/return42/sphkerneldoc.git
>
> sphkerneldoc.git is a small project started this weekend, within
> this project I show you, how migration could be done and
> we can discuss concerns like "tables and cell-spans" by example.
>
> Believe me, most concerns discussed in this thread are a leak of
> knowledge. I'am working with sphinx-doc since 7 years, switched
> over from DocBook (escaped from a 8 years lasting XML hell).
> DocBook and sphinx-doc are complete different, so sphinx-doc
> might feels odd in the first time, but if you have switched
> like me, you will never go back again.
>
>>> Dan keeps bringing up the active community in Asciidoctor, and how
>>> they're fixing things up as we speak... which is great, but Sphinx is
>>> here now, packaged and shipping in distros ready to use. It seems that
>>> of the two, an Asciidoctor based toolchain is currently more in need of
>>> hacking and extending to meet our needs. Which brings us to the
>>> implementation language, Python vs. Ruby.
>>>
>>> I won't make the mistake of comparing the relative merits of the
>>> languages, but I'll boldly claim the set of kernel developers who know
>>> Python is likely larger than the set of kernel developers who know Ruby
>>> [citation needed]. AFAICT there are no Ruby tools in the kernel tree,
>>> but there is a bunch of Python. My own very limited and subjective
>>> experience with other tools around the kernel is that Python is much
>>> more popular than Ruby. So my claim here is that we're in a better
>>> position to hack on Sphinx extensions ourselves than Asciidoctor.
>>
>> Sorry, but I don't buy it. Python is, IMHO, a mess: each new version
>> is incompatible with the previous one, and requires the source to
>> change, in order to use a newer version than the one used to write
>> the code. So, when talking about Python, we're actually talking about
>> several different dialects that don't talk well to each other.
>
> Sorry, you are complete wrong ... I'am 15 years python programmer,
> shipped out huge projects with my customers ... we never have seen
> these problems ... sorry ...
>
>
>> I don't know about Ruby. So far, I don't have anything against (or in
>> favor) of it. I bet most Kernel developers would actually prefer a
>> toolchain in C. If such tool doesn't exist, anything else seems
>> equally the same ;)
>
> Why we are talking about script languages? What needed is a
> authoring system, which is as near as possible to the developers,
> which are the authors.
>
> Sphinx-Doc is a standard authoring-tool versioned, maintained
> and extended by thousands of developers ...
>
>
>>> My conclusion is that Sphinx covers the vast majority of the needs of
>>> our documentation producers and consumers, in an amazing way, out of the
>>> box, better than Asciidoctor.
>>>
>>> Which brings us to the minority and the parts where Sphinx falls short,
>>> media documentation in particular. It's complex documentation, with very
>>> specific requirements on the output, especially that many things remain
>>> exactly as they are now. It also feels like the target is more to have
>>> standalone media documentation, and not so much to be aligned with and
>>> be part of the rest of the kernel documentation.
>>>
>>> I want to question the need to have all kernel documentation use tools
>>> that meet the strict requirements of the outlier, when there's a better
>>> alternative for the vast majority of the documentation. Especially when
>>> Asciidoctor isn't a ready solution for media documentation either.
>>>
>>> In summary, my proposal is to go with Sphinx, leave media docs as
>>> DocBook for now, and see if and how they can be converted to
>>> Sphinx/reStructuredText later on when we have everything else in
>>> place. It's not the perfect outcome, but IMHO it's the best overall
>>> choice.
>>
>> Well, this could be done. We don't have any good reason to move
>> the media docs out of DocBook.
>
> Sorry but again wrong: you lost many of the authors which are
> frustrated by a XML markup and you lost many developers to improve
> the toolchain, frustrated by a complicated DocBook-XML XSLT
> toolchain with SGML markup from the middle of the last epoch.
>
>> On the contrary, this means an extra
>> work. The only advantage is that it is a way simpler to write
>> documentation with a markup language, but converting from the PoC
>> to its integration at the Kernel tree still require lots of work,
>> specially due to the cross-refs "magic" scripts that we have under
>> Documentation/DocBook/media/Makefile.
>
> Yes, you are right, migration is a process not a one shot
> job, as I mentioned before. You are a great programmer, your
> documentation is also great, this invest should be preserved.
> So lets take a try. It would be a honor for me to show
> you all theses steps by example on my repository (see above).
>
>> As I said, the only big drawback is to keep depending on two
>> different tools for kernel-doc and for media documentation.
>
> -- Markus --
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
next prev parent reply other threads:[~2016-04-08 15:13 UTC|newest]
Thread overview: 94+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-02-13 21:53 Kernel docs: muddying the waters a bit Jonathan Corbet
2016-02-14 0:57 ` Keith Packard
2016-02-14 12:27 ` Daniel Vetter
2016-02-14 16:27 ` Keith Packard
2016-02-17 22:14 ` Jonathan Corbet
2016-02-17 22:29 ` Daniel Vetter
2016-02-18 9:11 ` Jani Nikula
2016-02-18 9:24 ` Daniel Vetter
2016-02-18 10:26 ` Mauro Carvalho Chehab
2016-02-18 11:23 ` Jani Nikula
2016-02-18 12:04 ` Mauro Carvalho Chehab
2016-02-18 12:07 ` Hans Verkuil
2016-02-18 12:44 ` Mauro Carvalho Chehab
2016-02-18 13:34 ` Patrick Boettcher
2016-02-18 13:01 ` Jonathan Corbet
2016-02-18 14:39 ` Daniel Vetter
2016-02-16 8:25 ` Jani Nikula
2016-02-16 16:08 ` Jonathan Corbet
2016-02-16 17:11 ` Jani Nikula
2016-02-16 19:13 ` Keith Packard
2016-02-16 19:59 ` Jonathan Corbet
2016-02-17 0:01 ` Keith Packard
2016-03-03 14:03 ` Jani Nikula
2016-03-03 14:13 ` Jonathan Corbet
2016-03-03 14:34 ` One Thousand Gnomes
2016-03-03 15:17 ` Jonathan Corbet
2016-03-03 15:45 ` Daniel Vetter
2016-03-03 18:50 ` Mauro Carvalho Chehab
2016-03-03 23:23 ` Keith Packard
2016-03-04 1:19 ` Mauro Carvalho Chehab
2016-03-04 8:29 ` Jani Nikula
2016-03-04 8:59 ` Johannes Stezenbach
2016-03-04 12:59 ` Mauro Carvalho Chehab
2016-03-04 14:09 ` Johannes Stezenbach
2016-03-06 2:29 ` Mauro Carvalho Chehab
2016-03-06 23:29 ` Johannes Stezenbach
2016-03-07 8:48 ` Johannes Stezenbach
2016-03-07 12:15 ` Mauro Carvalho Chehab
2016-03-07 12:19 ` Mauro Carvalho Chehab
2016-03-04 7:28 ` Russel Winder
2016-03-04 7:46 ` Jani Nikula
2016-03-08 4:53 ` Russel Winder
[not found] ` <CAKeHnO6sSV1x2xh_HgbD5ddZ8rp+SVvbdjVhczhudc9iv_-UCQ@mail.gmail.com>
2016-03-08 9:49 ` Jani Nikula
2016-03-08 11:29 ` Mauro Carvalho Chehab
[not found] ` <CAKeHnO7R25knFH07+3trdi0ZotsrEE+5ZzDZXdx33+DUW=q2Ug@mail.gmail.com>
2016-03-08 13:39 ` Mauro Carvalho Chehab
2016-03-08 15:39 ` Mauro Carvalho Chehab
2016-03-09 21:27 ` Mauro Carvalho Chehab
2016-03-10 10:25 ` Jani Nikula
2016-03-10 15:21 ` Mauro Carvalho Chehab
2016-03-13 15:33 ` Markus Heiser
2016-04-08 15:12 ` Markus Heiser [this message]
2016-04-12 9:18 ` Hans Verkuil
2016-04-12 15:46 ` Jonathan Corbet
2016-04-18 9:49 ` Markus Heiser
2016-04-27 14:28 ` Grant Likely
2016-05-03 14:31 ` Daniel Vetter
2016-05-03 15:54 ` Keith Packard
2016-05-04 9:34 ` Markus Heiser
2016-05-04 9:58 ` Jani Nikula
2016-05-04 12:40 ` Markus Heiser
2016-05-04 13:41 ` Jani Nikula
2016-05-04 15:09 ` Jonathan Corbet
2016-05-04 13:43 ` Daniel Vetter
2016-05-04 14:18 ` Daniel Vetter
2016-05-04 14:57 ` Jonathan Corbet
2016-05-04 15:02 ` Daniel Vetter
2016-05-04 16:32 ` Daniel Vetter
2016-05-04 15:44 ` Jani Nikula
2016-05-04 16:38 ` Mauro Carvalho Chehab
2016-05-04 15:55 ` Markus Heiser
2016-05-04 16:13 ` Jani Nikula
2016-05-04 16:50 ` Mauro Carvalho Chehab
2016-05-04 16:59 ` Jonathan Corbet
2016-05-04 17:57 ` Mauro Carvalho Chehab
2016-05-05 13:02 ` Jonathan Corbet
2016-05-05 13:23 ` Mauro Carvalho Chehab
2016-05-06 11:23 ` Markus Heiser
2016-05-06 11:44 ` Markus Heiser
[not found] ` <20160506083529.31ad2fa0@recife.lan>
[not found] ` <BAE3C147-6C21-4242-BD3C-8989C1626E10@darmarit.de>
[not found] ` <20160506104210.12197832@recife.lan>
2016-05-06 14:27 ` Markus Heiser
2016-05-06 15:06 ` Jani Nikula
2016-05-06 15:23 ` Mauro Carvalho Chehab
2016-05-06 15:35 ` Markus Heiser
2016-05-06 15:52 ` Jani Nikula
2016-05-06 15:14 ` Mauro Carvalho Chehab
2016-05-04 16:15 ` Mauro Carvalho Chehab
2016-05-06 10:05 ` Markus Heiser
[not found] ` <20160506080304.56307066@recife.lan>
2016-05-06 16:26 ` Markus Heiser
2016-05-06 17:06 ` Mauro Carvalho Chehab
[not found] ` <20160412105850.50e02108@recife.lan>
2016-04-18 8:10 ` Markus Heiser
2016-04-18 11:16 ` Mauro Carvalho Chehab
[not found] ` <CAKeHnO7_7k8Qc5Jmu_x2OzAVT4YXxW8PSe_m6QUP-8V7XxbTVw@mail.gmail.com>
2016-03-08 13:30 ` Mauro Carvalho Chehab
2016-03-08 13:58 ` Jani Nikula
[not found] ` <CAKeHnO7e5Escm0Ndm50eFX-qUXf7Lg9n=iXvwUGjz2M4KHLMsQ@mail.gmail.com>
2016-03-09 8:57 ` Jani Nikula
2016-03-07 3:48 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8992F589-5B66-4BDB-807A-79AC8644F006@darmarit.de \
--to=markus.heiser@darmarit.de \
--cc=corbet@lwn.net \
--cc=dan@opendevise.io \
--cc=daniel.vetter@ffwll.ch \
--cc=graham.whaley@linux.intel.com \
--cc=hverkuil@xs4all.nl \
--cc=jani.nikula@intel.com \
--cc=keithp@keithp.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@osg.samsung.com \
--cc=russel@winder.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).