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 mostly of Charles Nutter, JRuby is invariably a faster platform for Ruby code than Ruby is. So yes ASCIIDoctor is JVM-based via JRuby, not Java-based. The real point here is that in a move from DocBook/XML as a documentation source, ASCIIDoctor is an excellent choice. -- Russel.=====Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder@ekiga.net41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.ukLondon SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
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 mostly of Charles Nutter, JRuby is invariably a faster platform for Ruby code than Ruby is. So yes ASCIIDoctor is JVM-based via JRuby, not Java-based. The real point here is that in a move from DocBook/XML as a documentation source, ASCIIDoctor is an excellent choice. -- Russel.=====Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder@ekiga.net41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.ukLondon SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
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 I believe the standard bearer for ASCIIdoc these days, albeit called ASCIIdoctor. > 2) It really is just a docbook pre-processor. Native html/latex > output > is poorly supported at best, and exposes only a small subset of > the > full capabilities of the input language. This is not true. Yes ASCIIDoc started as a DocBook/XML frontend so as to use a sane :-) markup language rather than XML (XML is a notation for consenting computers only), but the current ASCIIDoctor toolchain deals very well in direct HTML and PDF generation, without needing a DocBook/XML toolchain. > As such, we would have to commit to using the ruby version and either > committing to fixing the native html output backend or continuing to > use > the rest of the docbook toolchain. Or trial the JVM-based ASCIIdoctor which is what the projects I am involved with chose to use. Perhaps as an example I can give you http:/ /gpars.website (it's a redirector) all the HTML and PDF is generated from ASCIIDoc source using ASCIIDoctor driven with a Gradle build system. This is still very much a work in progress (by Jim Northrop, not me currently), but I like it. > We could insist on using the python version, of course. I spent a bit > of > time hacking that up to add 'real' support for a table-of-contents in > the native HTML backend and it looks like getting those changes > upstreamed would be reasonably straightforward. However, we'd end up > 'owning' the code, and I'm not sure we want to. If the Python version is really not being maintained, I would suggest that unless you want to take over the project and be it's maintainer, you would be better advised to use a different version. -- Russel.=========Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder@ekiga.net41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.ukLondon SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
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 I believe the standard bearer for ASCIIdoc these days, albeit called ASCIIdoctor. > 2) It really is just a docbook pre-processor. Native html/latex > output > is poorly supported at best, and exposes only a small subset of > the > full capabilities of the input language. This is not true. Yes ASCIIDoc started as a DocBook/XML frontend so as to use a sane :-) markup language rather than XML (XML is a notation for consenting computers only), but the current ASCIIDoctor toolchain deals very well in direct HTML and PDF generation, without needing a DocBook/XML toolchain. > As such, we would have to commit to using the ruby version and either > committing to fixing the native html output backend or continuing to > use > the rest of the docbook toolchain. Or trial the JVM-based ASCIIdoctor which is what the projects I am involved with chose to use. Perhaps as an example I can give you http:/ /gpars.website (it's a redirector) all the HTML and PDF is generated from ASCIIDoc source using ASCIIDoctor driven with a Gradle build system. This is still very much a work in progress (by Jim Northrop, not me currently), but I like it. > We could insist on using the python version, of course. I spent a bit > of > time hacking that up to add 'real' support for a table-of-contents in > the native HTML backend and it looks like getting those changes > upstreamed would be reasonably straightforward. However, we'd end up > 'owning' the code, and I'm not sure we want to. If the Python version is really not being maintained, I would suggest that unless you want to take over the project and be it's maintainer, you would be better advised to use a different version. -- Russel.=========Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder@ekiga.net41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.ukLondon SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
Re: V4L docs and docbook
On Thu, 2016-02-18 at 07:28 -0200, Mauro Carvalho Chehab wrote: > Em Thu, 18 Feb 2016 07:10:14 -0200 > […] > > Stupid me: it should be just: > asciidoc book.asciidoc > > Still, there are lots of broken things there, and lots of errors when > building it: > https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html > > Ok, I would expect the need to handling some things manually, but > it worries that it broke the tables. For example, see > "Table 1. Control IDs" at https://mchehab.fedorapeople.org/media-kabi > -docs-test/book.html > > It was mapped as a 3 cols table, but this is how it should be, > instead: > https://linuxtv.org/downloads/v4l-dvb-apis/control.html > > As this table has actually 5 cols, because some controls have a list > of multiple values (see V4L2_CID_COLORFX for example). I will not be able to do anything to help with any of this today, but I can try and take a look tomorrow. Certainly an automated translation will not do all the complicated bits, that will need manual intervention. I may well be able to assist on this. I think the transform from DocBook/XML is worth a bit of up front effort now, so as to make everything so much easier for all concerned in the future. Obviously I do not have data relating to this project, just experience and anecdotal evidence from others. -- Russel. ===== Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.win...@ekiga.net 41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
Re: V4L docs and docbook
On Thu, 2016-02-18 at 07:28 -0200, Mauro Carvalho Chehab wrote: > Em Thu, 18 Feb 2016 07:10:14 -0200 > […] > > Stupid me: it should be just: > asciidoc book.asciidoc > > Still, there are lots of broken things there, and lots of errors when > building it: > https://mchehab.fedorapeople.org/media-kabi-docs-test/book.html > > Ok, I would expect the need to handling some things manually, but > it worries that it broke the tables. For example, see > "Table 1. Control IDs" at https://mchehab.fedorapeople.org/media-kabi > -docs-test/book.html > > It was mapped as a 3 cols table, but this is how it should be, > instead: > https://linuxtv.org/downloads/v4l-dvb-apis/control.html > > As this table has actually 5 cols, because some controls have a list > of multiple values (see V4L2_CID_COLORFX for example). I will not be able to do anything to help with any of this today, but I can try and take a look tomorrow. Certainly an automated translation will not do all the complicated bits, that will need manual intervention. I may well be able to assist on this. I think the transform from DocBook/XML is worth a bit of up front effort now, so as to make everything so much easier for all concerned in the future. Obviously I do not have data relating to this project, just experience and anecdotal evidence from others. -- Russel. ===== Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.win...@ekiga.net 41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
Re: V4L docs and docbook
On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > […] > > We have 2 types of documentation for the Kernel part of the > subsystem, > Both using DocBook: > - The uAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-apis > - The kAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > mediadev.html […] I may not be introducing new data here but… Whilst ReStructuredText and Markdown are fairly popular text markup languages, they are not related to the DocBook/XML toolchain. Many people, especially authors of books etc. are not really willing to write in DocBook/XML even though it is the re-purposable representation of choice for most of the major publishers. This led to ASCIIDoc. ASCIIDoc is a plain text markup language in the same way ReStructuredText and Markdown are, but it's intention was always to be a lightweight front end to DocBook/XML so as to allow authors to write in a nice markup language but work with the DocBook/XML toolchain. ASCIIDoc has gained quite a strong following. So much so that it now has a life of its own separate from the DocBook/XML tool chain. There is ASCIIDoctor which generates PDF, HTML,… from the source without using DocBook/XML, yet the source can quite happily go through a DocBook/XML toolchain as well. Many of the open source projects I am involved with are now using ASCIIDoctor as the documentation form. This has increased the number of non-main-contributor contributions via pull requests. It is so much easier to work with ASCIIDoc(tor) source than DocBook/XML source. -- Russel. ========= Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.win...@ekiga.net 41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
Re: V4L docs and docbook
On Wed, 2016-02-17 at 21:51 -0200, Mauro Carvalho Chehab wrote: > […] > > We have 2 types of documentation for the Kernel part of the > subsystem, > Both using DocBook: > - The uAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-apis > - The kAPI documentation: > https://linuxtv.org/downloads/v4l-dvb-internals/device-drivers/ > mediadev.html […] I may not be introducing new data here but… Whilst ReStructuredText and Markdown are fairly popular text markup languages, they are not related to the DocBook/XML toolchain. Many people, especially authors of books etc. are not really willing to write in DocBook/XML even though it is the re-purposable representation of choice for most of the major publishers. This led to ASCIIDoc. ASCIIDoc is a plain text markup language in the same way ReStructuredText and Markdown are, but it's intention was always to be a lightweight front end to DocBook/XML so as to allow authors to write in a nice markup language but work with the DocBook/XML toolchain. ASCIIDoc has gained quite a strong following. So much so that it now has a life of its own separate from the DocBook/XML tool chain. There is ASCIIDoctor which generates PDF, HTML,… from the source without using DocBook/XML, yet the source can quite happily go through a DocBook/XML toolchain as well. Many of the open source projects I am involved with are now using ASCIIDoctor as the documentation form. This has increased the number of non-main-contributor contributions via pull requests. It is so much easier to work with ASCIIDoc(tor) source than DocBook/XML source. -- Russel. ========= Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.win...@ekiga.net 41 Buckmaster Roadm: +44 7770 465 077 xmpp: rus...@winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder signature.asc Description: This is a digitally signed message part
