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 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 tables on this page: > > >

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

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 (sphinx) build infrastructure, including >> >> * a folder for sphinx docs:

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

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

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 sphinx docs: > > ./Documentation/sphinx/ I'm already working on a patch series taking a

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

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

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

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

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

Em Wed, 4 May 2016 10:59:36 -0600 Jonathan Corbet escreveu: > 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

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

Em Wed, 4 May 2016 19:13:21 +0300 Jani Nikula escreveu: > 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

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: 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 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, 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

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

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 Wed, 04 May 2016 16:41:50 +0300 Jani Nikula wrote: > On Wed, 04 May 2016, Markus Heiser wrote: > > In reST the directive might look like: > > > > - > > Device Instance and Driver Handling > > === > > > >

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

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, 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, 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 kernel-doc. IMO the extraction from kernel-doc > > comments must

Re: Kernel docs: muddying the waters a bit

On Wed, 04 May 2016, Markus Heiser wrote: >> What do you mean by ".tmpl workflow"? > > Sorry for bad naming, I addressed the DOCPROC build process which builds > the .xml files from .tmpl files ... Yeah, I know more about this part than I care. I was just wondering

Re: Kernel docs: muddying the waters a bit

Hi Jani, Am 04.05.2016 um 11:58 schrieb Jani Nikula : > On Wed, 04 May 2016, Markus Heiser wrote: >> but I think this will not by very helpful, as long as you miss >> a similar ".tmpl" workflow for reST documents. >> >> I'am working on a reST

Re: Kernel docs: muddying the waters a bit

On Wed, 04 May 2016, Markus Heiser wrote: > but I think this will not by very helpful, as long as you miss > a similar ".tmpl" workflow for reST documents. > > I'am working on a reST directive (named: "kernel-doc") to provide a > similar ".tmpl" workflow within plain

Re: Kernel docs: muddying the waters a bit

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 option that should > allow us to address everyone's concerns eventually? Of course the > first one

Re: Kernel docs: muddying the waters a bit

Daniel Vetter writes: > So sphinx/rst y/n? Jon, is that ok with you from the doc maintainer > pov? I think the right answer for today is to use sphinx to generate docs From inline comments, to encourage outline docs to give it a try but to allow doc writers to use

Re: Kernel docs: muddying the waters a bit

Hi all, So sounds like moving ahead with rst/sphinx is the option that should allow us to address everyone's concerns eventually? Of course the first one won't have it all (media seems really tricky), but I'd like to get something awesome in this area closer to mainline. I'm stalling on typing

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: 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

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

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 converts 99% of the docs well ... to gain an impression how > kernel-docs could

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

Am 10.03.2016 um 16:21 schrieb Mauro Carvalho Chehab : > Em Thu, 10 Mar 2016 12:25:58 +0200 > Jani Nikula escreveu: > >> TL;DR? Skip to the last paragraph. >> >> On Wed, 09 Mar 2016, Mauro Carvalho Chehab wrote: >>> I

Re: Kernel docs: muddying the waters a bit

Em Thu, 10 Mar 2016 12:25:58 +0200 Jani Nikula escreveu: > TL;DR? Skip to the last paragraph. > > On Wed, 09 Mar 2016, Mauro Carvalho Chehab wrote: > > I guess the conversion to asciidoc format is now in good shape, > > at least to demonstrate

Re: Kernel docs: muddying the waters a bit

TL;DR? Skip to the last paragraph. On Wed, 09 Mar 2016, Mauro Carvalho Chehab 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

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

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 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 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, 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

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

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

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

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

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 now it recognized > > it as a table. Yet, the table was very badly formated: > > > >

Re: Kernel docs: muddying the waters a bit

On Thu, 03 Mar 2016 16:03:14 +0200 Jani Nikula wrote: > This stalled a bit, but the waters are still muddy... So I've been messing with this a bit; wanted to do a proper patch posting but I'm fried and mostly out of time for the moment. The results I'm getting now can be

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 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, 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 > easy to fix, but I want to see if the cssclass will also work for > the pdf output as well.

Re: Kernel docs: muddying the waters a bit

Em Fri, 04 Mar 2016 10:29:08 +0200 Jani Nikula escreveu: > On Fri, 04 Mar 2016, Mauro Carvalho Chehab wrote: > > Em Thu, 03 Mar 2016 15:23:23 -0800 > > Keith Packard escreveu: > > > >> Mauro Carvalho Chehab

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

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

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

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

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

Em Thu, 03 Mar 2016 07:13:05 -0700 Jonathan Corbet escreveu: > On Thu, 03 Mar 2016 16:03:14 +0200 > Jani Nikula wrote: > > > This stalled a bit, but the waters are still muddy... > > I've been dealing with real-world obnoxiousness, something which

Re: Kernel docs: muddying the waters a bit

On Thu, Mar 3, 2016 at 4:17 PM, Jonathan Corbet wrote: > I assume you're referring to gtk-doc? It's web page > (http://www.gtk.org/gtk-doc/) starts by noting that it's "a bit awkward to > setup and use"; they recommend looking at Doxygen instead. So I guess I'm > not really sure

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

> 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 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 time to mess with

Re: Kernel docs: muddying the waters a bit

On Sat, 13 Feb 2016, Jonathan Corbet 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, but the waters are