Asciidoc, an alternative for documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Asciidoc, an alternative for documentation

Boost - Dev mailing list
I've been experimenting with Asciidoc-based documentation, using
Boost.Assert as my guinea pig. The good thing about Asciidoc is that Github
shows a preview and you can edit it directly on github.com. This is how the
source looks there:

https://github.com/boostorg/assert/blob/feature/asciidoc/doc/index.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/assert.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/current_function.adoc

This is how the generated HTML documentation looks, using the default
stylesheet, without any customizations on my part:

https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html

And this is how the generated PDF looks:

http://pdimov.com/tmp/assert.pdf

The tool that produces these is Asciidoctor, http://asciidoctor.org/ .


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:

> This is how the generated HTML documentation looks, using the default
> stylesheet, without any customizations on my part:
>
> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html
>

I've converted all of Boost.Http documentation to asciidoc. I don't intend
to use QuickBook/BoostBook again. Too much NIH syndrome and too much
inconvenient.

I use the following options to generate the HTML:

asciidoctor -a toc=left -a toclevels=3 -a sectnums -a sectnumlevels=4
http.adoc

And the following to generate the ePUB:

asciidoctor -b docbook5 http.adoc
pandoc -f docbook http.xml -o http.epub

I was considering paying someone to design a Boost-like theme and the
opened the Boost.Asio documentation. I changed my mind. There is no reason
somebody would like to mirror this theme.

It's infinitely easier to write documentation using asciidoc, and this is a
plus also to receive contributions. Nobody outside Boost know how to get
boostbook up and ready to generate HTML, PDF and ePUB.

Also, asciidoc was designed to make syntactic elements directly mirror
docbook semantics. So you have great Docbook output with a syntax that is
as pleasant to use as MarkDown.

Also, I've found many different ways to generate PDF using asciidoc. All of
them are pretty different when you compare the output of each process. Just
noting in case you didn't like this one generated PDF.

Have fun playing with asciidoc.

--
Vinícius dos Santos Oliveira
https://vinipsmaker.github.io/

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:

> 2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:
>
>> This is how the generated HTML documentation looks, using the default
>> stylesheet, without any customizations on my part:
>>
>> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html
>>
>
> I've converted all of Boost.Http documentation to asciidoc. I don't intend
> to use QuickBook/BoostBook again. Too much NIH syndrome and too much
> inconvenient.

Using quickbook has always appeared easy to me. Generating html and pdf
doc from quickbook source involves a number of steps that need to be
correctly setup via a jamfile, and I think this is what always appears
hard to others.

I am certainly not against other methods of writing Boost documentation
and will look at asciidoc. But I did want to point out that I do not
think the issue with quickbook is really the quickbook syntax itself.
Others of course may well disagree with this assessment.

>
> I use the following options to generate the HTML:
>
> asciidoctor -a toc=left -a toclevels=3 -a sectnums -a sectnumlevels=4
> http.adoc
>
> And the following to generate the ePUB:
>
> asciidoctor -b docbook5 http.adoc
> pandoc -f docbook http.xml -o http.epub
>
> I was considering paying someone to design a Boost-like theme and the
> opened the Boost.Asio documentation. I changed my mind. There is no reason
> somebody would like to mirror this theme.
>
> It's infinitely easier to write documentation using asciidoc, and this is a
> plus also to receive contributions. Nobody outside Boost know how to get
> boostbook up and ready to generate HTML, PDF and ePUB.
>
> Also, asciidoc was designed to make syntactic elements directly mirror
> docbook semantics. So you have great Docbook output with a syntax that is
> as pleasant to use as MarkDown.
>
> Also, I've found many different ways to generate PDF using asciidoc. All of
> them are pretty different when you compare the output of each process. Just
> noting in case you didn't like this one generated PDF.
>
> Have fun playing with asciidoc.
>



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoc, an alternative for documentation

Boost - Dev mailing list
On Tue, Jun 6, 2017 at 7:10 AM, Edward Diener via Boost
<[hidden email]> wrote:
> On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:
>>
>> 2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost <[hidden email]>:
>>
>>> This is how the generated HTML documentation looks, using the default
>>> stylesheet, without any customizations on my part:
>>>
>>> https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html

Looks nice. I am not familiar with asciidoc...

* Does ascii interface with Doxygen? For example, can you embed in the
asciidoc output a reference section generated by Doxygen and have
hyperlinks in between the ascidoc and Doxygen sections? (Similar to
Quickbook [xinclude ...].)

* Does asciidoc allow to show code snips marked in an external source
file? For example, to show example code snips in Quickbook using
[import <file-name>] and then [abc], where //[abc ... //] are used as
markers in file-name.

> Using quickbook has always appeared easy to me. Generating html and pdf doc
> from quickbook source involves a number of steps that need to be correctly
> setup via a jamfile, and I think this is what always appears hard to others.

This is my experience as well. For example, if there was a
"pre-compiled" distributable of Quickbook that did not require to
download Boost and did not use BJam (as least not require to the users
to use BJam directly), Quickbook would be easier to use.

--Lorenzo

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Loading...