Re: Kernel docs: muddying the waters a bit

Jonathan Corbet writes: > Indeed, I doubt many people want the DocBook itself. Might be nice to actually have a set of requirements before anyone tries to select a suitable system then :-) Here's my current set: asciidocsphinx htmlvia docbook native

Re: Kernel docs: muddying the waters a bit

On Fri, 04 Mar 2016, Russel Winder wrote: > On Thu, 2016-03-03 at 15:23 -0800, Keith Packard wrote: >>   1) the python version (asciidoc) appears to have been abandoned in >>  favor of the ruby version.  > > This is I think true, however the Java-based tool chain

Re: Kernel docs: muddying the waters a bit

On Wed, May 4, 2016 at 3:43 PM, Daniel Vetter wrote: > I'd really like to converge on the markup question, so that we can start > using all the cool stuff with impunity in gpu documentations. Aside: If we decide this now I could send in a pull request for the rst/sphinx

Re: Kernel docs: muddying the waters a bit

On Wed, 04 May 2016, Jonathan Corbet wrote: > The sphinx/rst approach does seem, to me, to be the right one, with the > existing DocBook structure remaining in place for those who want/need > it. I'm inclined toward my stuff as a base to work with, obviously :) But > it's hackish

Re: Kernel docs: muddying the waters a bit

On Sat, 13 Feb 2016, Jonathan Corbet <cor...@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? This stalled a bit,

Re: Kernel docs: muddying the waters a bit

On Tue, 16 Feb 2016 10:25:49 +0200 Jani Nikula 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

Re: Kernel docs: muddying the waters a bit

On Tue, 16 Feb 2016, Jonathan Corbet 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

Re: Kernel docs: muddying the waters a bit

On Fri, 2016-03-04 at 09:46 +0200, Jani Nikula wrote: > […] > If we're talking about the same asciidoctor (http://asciidoctor.org/) > it's written in ruby but you can apparently run it in JVM using > JRuby. Calling it Java-based is misleading. Indeed, I was somewhat imprecise. Thanks to the work

Re: Kernel docs: muddying the waters a bit

Em Tue, 08 Mar 2016 05:13:13 -0700 Dan Allen escreveu: > On Tue, Mar 8, 2016 at 4:29 AM, Mauro Carvalho Chehab < > mche...@osg.samsung.com> wrote: > > > pandoc did a really crap job on the conversion. To convert this > > into something useful, we'll need to spend a lot of

Re: Kernel docs: muddying the waters a bit

Mauro Carvalho Chehab writes: > On my tests, Sphinix seemed too limited to format tables. Asciidoc > produced an output that worked better. Yes, asciidoc has much more flexibility in table formatting, including the ability to control text layout within cells and full

Re: Kernel docs: muddying the waters a bit

> DocBook is a means to an end; nobody really wants DocBook itself as far > as I can tell. We only have docbook because it was the tool of choice rather a lot of years ago to then get useful output formats. It was just inherited when borrowed the original scripts from Gnome/Gtk. It's still the

Re: Kernel docs: muddying the waters a bit

On Thu, 03 Mar 2016 16:03:14 +0200 Jani Nikula <jani.nik...@intel.com> wrote: > This stalled a bit, but the waters are still muddy... I've been dealing with real-world obnoxiousness, something which won't come to an immediate end, unfortunately. But I have been taking some tim

Re: Kernel docs: muddying the waters a bit

On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: > On Sun, 14 Feb 2016 13:27:04 +0100 > Daniel Vetter wrote: > >> One concern/open I have for pro/cons are the hyperlinks from kerneldoc >> comments. Currently we have the postproc hack, iirc Jani's

Re: Kernel docs: muddying the waters a bit

On Tue, 08 Mar 2016, Dan Allen wrote: > One of the key goals of the Asciidoctor project is to be able to directly > produce a wide variety of outputs from the same source (without DocBook). > We've added flexibility and best practices into the syntax and matured the >

Re: Kernel docs: muddying the waters a bit

Em Tue, 08 Mar 2016 05:09:40 -0700 Dan Allen escreveu: > Jani wrote: > > > there was no support for chunked, or split > > to chapters, HTML, and the single page result was simply way too big. > > > > That's not entirely true. First, you can pre-split at the source level >

Re: Kernel docs: muddying the waters a bit

On Tue, 08 Mar 2016, Dan Allen wrote: > That's not entirely true. First, you can pre-split at the source level > using includes and generate output for each of the masters. That's what I > tend to do and it works really well since these are logical split points. I need to

Re: Kernel docs: muddying the waters a bit

Em Tue, 8 Mar 2016 10:39:22 -0300 Mauro Carvalho Chehab escreveu: > Em Tue, 08 Mar 2016 05:13:13 -0700 > Dan Allen escreveu: > > > On Tue, Mar 8, 2016 at 4:29 AM, Mauro Carvalho Chehab < > > mche...@osg.samsung.com> wrote: > > > > > pandoc

Re: Kernel docs: muddying the waters a bit

On Fri, Mar 04, 2016 at 10:29:08AM +0200, Jani Nikula wrote: > On Fri, 04 Mar 2016, Mauro Carvalho Chehab wrote: > > > > If, on the other hand, we decide to use RST, we'll very likely need to > > patch it to fulfill our needs in order to add proper table support. > > I've

Re: Kernel docs: muddying the waters a bit

Em Fri, 04 Mar 2016 15:09:09 +0100 Johannes Stezenbach escreveu: > On Fri, Mar 04, 2016 at 09:59:50AM -0300, Mauro Carvalho Chehab wrote: > > > > 3) I tried to use a .. cssclass, as Johannes suggested, but > > I was not able to include the CSS file. I suspect that this is > >

Re: Kernel docs: muddying the waters a bit

On Fri, 06 May 2016, Markus Heiser wrote: > Am 06.05.2016 um 17:06 schrieb Jani Nikula : > >> On Fri, 06 May 2016, Markus Heiser wrote: >>> @Jonathan: what do you think? Should I prepare a patch >>> with a basic reST

Re: Kernel docs: muddying the waters a bit

On Wed, 4 May 2016 16:18:27 +0200 Daniel Vetter wrote: > > I'd really like to converge on the markup question, so that we can start > > using all the cool stuff with impunity in gpu documentations. > > Aside: If we decide this now I could send in a pull request for the

Re: Kernel docs: muddying the waters a bit

On Wed, 4 May 2016 14:57:38 -0300 Mauro Carvalho Chehab wrote: > Also, media documentation is not just one more documentation. It is > the biggest one we have, and that has more changes than any other > documentation under Documentation/DocBook: > > $ git lg --since

Re: Kernel docs: muddying the waters a bit

Hi Mauro, Am 04.05.2016 um 18:15 schrieb Mauro Carvalho Chehab : > Em Wed, 4 May 2016 11:34:08 +0200 > Markus Heiser escreveu: > >> Hi all, (hi Jonathan, please take note of my offer below) >> >> Am 03.05.2016 um 16:31 schrieb Daniel Vetter

Re: Kernel docs: muddying the waters a bit

On Tue, Apr 12, 2016 at 4:46 PM, Jonathan Corbet wrote: > On Fri, 8 Apr 2016 17:12:27 +0200 > Markus Heiser wrote: > >> motivated by this MT, I implemented a toolchain to migrate the kernel’s >> DocBook XML documentation to reST markup. >> >> It

Re: [PATCH linux v7 3/6] hwmon: occ: Add I2C transport implementation for SCOM operations

I2C transport implementation independent of any P8 details, and having it separate* is no more abstract than the core performing SCOMs through the FSI interface when that's available. I feel like it's muddying the waters conceptually to bury P8 details in the implementation of a SCOM transport layer

Re: [PATCH] doc: memory-barriers: reStructure Text

st ... your cooperation and your criticism is needed and welcome. Please let me invite you / read on: There are other plain-text markups e.g. AsciiDoc or Markdown. The reST markup and the Sphinx-builder is a compromise from a evaluation in 2016 (see linux-doc ML subject "muddying the water

Re: Kernel docs: muddying the waters a bit

On Thu, 18 Feb 2016, Daniel Vetter wrote: > On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: >> On Sun, 14 Feb 2016 13:27:04 +0100 >> Daniel Vetter wrote: >> >>> One concern/open I have for pro/cons are the hyperlinks from

Re: Kernel docs: muddying the waters a bit

Em Tue, 8 Mar 2016 12:39:21 -0300 Mauro Carvalho Chehab escreveu: > Pandoc failed to fully convert it, but at least it left all the texts, > with prevented rewriting it from scratch. This is the manual fix > I applied to it: > >

Re: Kernel docs: muddying the waters a bit

Em Thu, 03 Mar 2016 15:23:23 -0800 Keith Packard escreveu: > Mauro Carvalho Chehab writes: > > > On my tests, Sphinix seemed too limited to format tables. Asciidoc > > produced an output that worked better. > > Yes, asciidoc has much more

Re: Kernel docs: muddying the waters a bit

On Thu, 2016-03-03 at 15:23 -0800, Keith Packard wrote: > […] > However, I think asciidoc has two serious problems: > >   1) the python version (asciidoc) appears to have been abandoned in >  favor of the ruby version.  This is I think true, however the Java-based tool chain Asciidoctor is

Re: Kernel docs: muddying the waters a bit

On Thu, 3 Mar 2016 14:34:25 + One Thousand Gnomes wrote: > We only have docbook because it was the tool of choice rather a lot of > years ago to then get useful output formats. It was just inherited when > borrowed the original scripts from Gnome/Gtk. It's still

Re: Kernel docs: muddying the waters a bit

On Wed, 09 Mar 2016, Dan Allen wrote: > On Tue, Mar 8, 2016 at 6:58 AM, Jani Nikula wrote: > >> I need to look into this again. Is there a specific option or directive >> to produce split output for includes? When I tried this, the result was >> just

Re: Kernel docs: muddying the waters a bit

Em Fri, 6 May 2016 18:06:49 +0300 Jani Nikula escreveu: > On Fri, 06 May 2016, Markus Heiser wrote: > > @Jonathan: what do you think? Should I prepare a patch > > with a basic reST (sphinx) build infrastructure, including > > > > * a folder for

Re: Kernel docs: muddying the waters a bit

On Wed, 04 May 2016, Markus Heiser wrote: > Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in > particular with your "MARKDOWNREADY := gpu.xml" process. > > As I understood, you convert markdown to docbook within the kernel-doc > script using pandoc's

Re: Kernel docs: muddying the waters a bit

Em Wed, 4 May 2016 11:34:08 +0200 Markus Heiser escreveu: > Hi all, (hi Jonathan, please take note of my offer below) > > Am 03.05.2016 um 16:31 schrieb Daniel Vetter : > > > Hi all, > > > > So sounds like moving ahead with rst/sphinx is the

Re: Kernel docs: muddying the waters a bit

On Wed, May 04, 2016 at 08:57:13AM -0600, Jonathan Corbet wrote: > On Wed, 4 May 2016 16:18:27 +0200 > Daniel Vetter wrote: > > > > I'd really like to converge on the markup question, so that we can start > > > using all the cool stuff with impunity in gpu documentations.

Re: Kernel docs: muddying the waters a bit

Em Wed, 4 May 2016 08:57:13 -0600 Jonathan Corbet escreveu: > On Wed, 4 May 2016 16:18:27 +0200 > Daniel Vetter wrote: > > > > I'd really like to converge on the markup question, so that we can start > > > using all the cool stuff with impunity in gpu

Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx)

xdepth: 1 kernel-doc-intro kernel-doc-syntax - rules like ":ref:", domains like ":c:type:" and directives like ".. toctree:" are a part of the (extended) reST syntax from sphinx, thats why standard docutils (like rst2*) will not work ... >

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

Re: Kernel docs: muddying the waters a bit

On Thu, Feb 18, 2016 at 10:11 AM, Jani Nikula wrote: > On Thu, 18 Feb 2016, Daniel Vetter wrote: >> On Wed, Feb 17, 2016 at 11:14 PM, Jonathan Corbet wrote: >>> On Sun, 14 Feb 2016 13:27:04 +0100 >>> Daniel Vetter

Re: Kernel docs: muddying the waters a bit

Em Mon, 7 Mar 2016 09:48:26 +0100 Johannes Stezenbach escreveu: > On Mon, Mar 07, 2016 at 12:29:08AM +0100, Johannes Stezenbach wrote: > > On Sat, Mar 05, 2016 at 11:29:37PM -0300, Mauro Carvalho Chehab wrote: > > > > > > I converted one of the big tables to CSV. At least

Re: Kernel docs: muddying the waters a bit

Em Mon, 7 Mar 2016 00:29:08 +0100 Johannes Stezenbach escreveu: > On Sat, Mar 05, 2016 at 11:29:37PM -0300, Mauro Carvalho Chehab wrote: > > > > I converted one of the big tables to CSV. At least now it recognized > > it as a table. Yet, the table was very badly formated: > >

Re: Kernel docs: muddying the waters a bit

On Wed, 4 May 2016 13:50:35 -0300 Mauro Carvalho Chehab wrote: > Em Wed, 4 May 2016 19:13:21 +0300 > Jani Nikula escreveu: > > I think we should go for vanilla sphinx at first, to make the setup step > > as easy as possible for everyone. > >

Re: Kernel docs: muddying the waters a bit

On Wed, May 4, 2016 at 5:02 PM, Daniel Vetter wrote: > On Wed, May 04, 2016 at 08:57:13AM -0600, Jonathan Corbet wrote: >> On Wed, 4 May 2016 16:18:27 +0200 >> Daniel Vetter wrote: >> >> > > I'd really like to converge on the markup question, so that we

Re: Kernel docs: muddying the waters a bit

Em Thu, 5 May 2016 07:02:10 -0600 Jonathan Corbet escreveu: > On Wed, 4 May 2016 14:57:38 -0300 > Mauro Carvalho Chehab wrote: > > > Also, media documentation is not just one more documentation. It is > > the biggest one we have, and that has more

Re: Kernel docs: muddying the waters a bit

Jonathan Corbet 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

Re: Kernel docs: muddying the waters a bit

Em Tue, 08 Mar 2016 11:49:35 +0200 Jani Nikula escreveu: > On Tue, 08 Mar 2016, Dan Allen wrote: > > One of the key goals of the Asciidoctor project is to be able to directly > > produce a wide variety of outputs from the same source (without DocBook).

Re: Kernel docs: muddying the waters a bit

On Fri, 04 Mar 2016, Mauro Carvalho Chehab wrote: > Em Thu, 03 Mar 2016 15:23:23 -0800 > Keith Packard escreveu: > >> Mauro Carvalho Chehab writes: >> >> > On my tests, Sphinix seemed too limited to format tables. Asciidoc >>

Re: Kernel docs: muddying the waters a bit

Am 04.05.2016 um 15:43 schrieb Daniel Vetter : > On Wed, May 04, 2016 at 02:40:29PM +0200, Markus Heiser wrote: >>> On Wed, 04 May 2016, Markus Heiser wrote: >>> I'd be *very* hesitant about adding the kind of things you do in >>> reformat_block_rst to

Re: Kernel docs: muddying the waters a bit

Hy Jani, Am 04.05.2016 um 18:13 schrieb Jani Nikula : >> Am 04.05.2016 um 17:09 schrieb Jonathan Corbet : >> >>> I think all of this makes sense. It would be really nice to have the >>> directives in the native sphinx language like that. I *don't* think

Re: Kernel docs: muddying the waters a bit

Hi Jani, I forget to mentioning, with a local copy of my kernel-doc script: https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc You could do reST markup in the source code comments and extract them. This might be a interim workaround which helps you not to edit source code

Re: Kernel docs: muddying the waters a bit

Hi Jonahtan, Am 12.04.2016 um 17:46 schrieb Jonathan Corbet : > On Fri, 8 Apr 2016 17:12:27 +0200 > Markus Heiser wrote: > >> motivated by this MT, I implemented a toolchain to migrate the kernel’s >> DocBook XML documentation to reST markup. >> >>

Re: Kernel docs: muddying the waters a bit

Em Fri, 6 May 2016 18:26:10 +0200 Markus Heiser escreveu: > Hi Mauro, > > Am 06.05.2016 um 13:03 schrieb Mauro Carvalho Chehab > : > > Yeah, it looks better, however table truncation seem to be > > happening also on other parts, like the

Re: Kernel docs: muddying the waters a bit

Hi all, hi Jonathan, Am 06.05.2016 um 15:42 schrieb Mauro Carvalho Chehab : > Em Fri, 6 May 2016 15:32:35 +0200 > Markus Heiser escreveu: > >> Hi Mauro, >> >> Am 06.05.2016 um 13:35 schrieb Mauro Carvalho Chehab >>

Re: Kernel docs: muddying the waters a bit

Em Fri, 6 May 2016 16:27:21 +0200 Markus Heiser escreveu: > Hi all, hi Jonathan, > > Am 06.05.2016 um 15:42 schrieb Mauro Carvalho Chehab > : > > > Em Fri, 6 May 2016 15:32:35 +0200 > > Markus Heiser escreveu: > >

Re: Kernel docs: muddying the waters a bit

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:

Re: Kernel docs: muddying the waters a bit

Hi Mauro, hi kernel-doc authors, Am 12.04.2016 um 15:58 schrieb Mauro Carvalho Chehab : > Em Fri, 8 Apr 2016 17:12:27 +0200 > Markus Heiser escreveu: > >> Hi kernel-doc authors, >> >> motivated by this MT, I implemented a toolchain to

Re: Kernel docs: muddying the waters a bit

On Sat, Mar 05, 2016 at 11:29:37PM -0300, Mauro Carvalho Chehab wrote: > > I converted one of the big tables to CSV. At least now it recognized > it as a table. Yet, the table was very badly formated: > > https://mchehab.fedorapeople.org/media-kabi-docs-test/rst_tests/packed-rgb.html > >

Re: Kernel docs: muddying the waters a bit

Em Mon, 18 Apr 2016 10:10:17 +0200 Markus Heiser escreveu: > Hi Mauro, hi kernel-doc authors, > > Am 12.04.2016 um 15:58 schrieb Mauro Carvalho Chehab > : > > > Em Fri, 8 Apr 2016 17:12:27 +0200 > > Markus Heiser