Re: V4L docs and docbook

2016-02-18 Thread Mauro Carvalho Chehab 
Em Thu, 18 Feb 2016 11:37:41 +0200
Jani Nikula  escreveu:

> On Thu, 18 Feb 2016, Mauro Carvalho Chehab  wrote:
> > Are there any tools that would convert from DocBook to ASCIIDoc?  
> 
> I used pandoc when I tested the asciidoc pipeline. Something along the
> lines of this for filtering docbook in stdin to asciidoc in stdout:
> 
> pandoc --atx-headers -f docbook -t asciidoc
>

Results are at:
https://mchehab.fedorapeople.org/media-kabi-docs-test/pandoc_asciidoc/

pandoc/asciidoc also broke the tables.


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: V4L docs and docbook

2016-02-18 Thread Jani Nikula 
On Thu, 18 Feb 2016, Mauro Carvalho Chehab  wrote:
> Are there any tools that would convert from DocBook to ASCIIDoc?

I used pandoc when I tested the asciidoc pipeline. Something along the
lines of this for filtering docbook in stdin to asciidoc in stdout:

pandoc --atx-headers -f docbook -t asciidoc


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: V4L docs and docbook

2016-02-18 Thread Jani Nikula 
On Thu, 18 Feb 2016, Russel Winder  wrote:
> 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.

We have been looking at asciidoc too, so much so that there are draft
patches by Jon and me to build some of the documentation from asciidoc
source. Both are in the thread starting at [1]. But we really need to
consider reStructuredText too [2].

I think this thread is about figuring out how much we really depend on
DocBook. There is a lot of pain in dealing with DocBook, especially as a
source format, but also as an intermediate format. If we can produce the
end results (html, pdf, man, ...) from the source markup directly, it's
a win.

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

See some of the other threads. Asciidoc seems to be in maintenance
mode. Asciidoctor depends on a ruby environment which is not met with
enthusiasm. The HTML output can only be chunked (split to several pages)
via the DocBook output. Sphinx is active, doesn't add a lot of new
dependencies, and seems to be able to natively output all the end
results people have so far said they care about.

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

I'm hopeful this holds for any of the lightweight markups.


BR,
Jani.


[1] http://lkml.kernel.org/r/1453764522-29030-1-git-send-email-cor...@lwn.net
[2] http://lkml.kernel.org/r/20160213145317.247c6...@lwn.net

-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

2016-02-18 Thread Daniel Vetter 
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  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(),
>>  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 func.
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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

2016-02-18 Thread Jani Nikula 
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 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(),
>  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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: V4L docs and docbook

2016-02-18 Thread Mauro Carvalho Chehab 
Em Thu, 18 Feb 2016 06:31:14 -0200
Mauro Carvalho Chehab  escreveu:

> Em Thu, 18 Feb 2016 08:17:00 +
> Russel Winder  escreveu:
> 
> > 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.   
> 
> Are there any tools that would convert from DocBook to ASCIIDoc?

Answering myself:

I found one tool at:
https://github.com/oreillymedia/docbook2asciidoc

That seemed to work. I ran it with:
$ make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: 
validity error : ID .* already defined"
$ xmllint --noent --postvalid 
"$PWD/Documentation/DocBook/media_api.xml" >/tmp/x.xml 2>/dev/null
$ java -jar saxon9he.jar -s /tmp/x.xml -o book.asciidoc d2a_docbook.xsl 
chunk-output=true

And it produced a series of documents, that I stored at:
https://mchehab.fedorapeople.org/media-kabi-docs-test/

I noticed, however, that it kept some things using DocBook xml. Perhaps
because some things cannot be translated to markup (see appa.asciidoc)?

Also, converting them to HTML produced me some errors, but perhaps because
I don't know what I'm doing ;)

What I did was:
for i in book-docinfo.xml *.asciidoc; do asciidoc $i; done

errors enclosed.

Yet, it seems there are some hope on using asciidoc for the kAPI
documentation.

Thanks,
Mauro

---

asciidoc: ERROR: book.asciidoc: line 9: only book doctypes can contain level 0 
sections
asciidoc: ERROR: ch01.asciidoc: line 588: only book doctypes can contain level 
0 sections
asciidoc: ERROR: ch02.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch03.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch03.asciidoc: line 370: illegal style name: capture example
asciidoc: ERROR: ch04.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch04.asciidoc: line 719: illegal style name: to do
asciidoc: ERROR: ch05.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch06.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch07.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: ERROR: ch07.asciidoc: line 907: illegal style name: Solution?
asciidoc: ERROR: ch07.asciidoc: line 2208: illegal style name: to do - OSS/ALSA
asciidoc: ERROR: appa.asciidoc: line 3: section title not permitted in 
delimited block
asciidoc: WARNING: appa.asciidoc: line 7: missing style: [blockdef-pass]: 
appendix
asciidoc: ERROR: appb.asciidoc: line 2: section title not permitted in 
delimited block
asciidoc: WARNING: appb.asciidoc: line 7: missing style: [paradef-default]: 
appendix
asciidoc: ERROR: appc.asciidoc: line 3: section title not permitted in 
delimited block
asciidoc: WARNING: appc.asciidoc: line 7: missing style: [blockdef-pass]: 
appendix
asciidoc: ERROR: appd.asciidoc: line 3: section title not permitted in 
delimited block
asciidoc: WARNING: appd.asciidoc: line 7: missing style: [blockdef-pass]: 
appendix
asciidoc: ERROR: appe.asciidoc: line 3: section title not permitted in 
delimited block
asciidoc: WARNING: appe.asciidoc: line 5: missing style: [paradef-default]: 
appendix
asciidoc: ERROR: book.asciidoc: line 142: section title not permitted in 
delimited block

Re: V4L docs and docbook

2016-02-18 Thread Mauro Carvalho Chehab 
Em Thu, 18 Feb 2016 08:17:00 +
Russel Winder  escreveu:

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

Are there any tools that would convert from DocBook to ASCIIDoc?

Thanks,
Mauro


pgp06fUKfAiNJ.pgp
Description: Assinatura digital OpenPGP