AsciiDoc is suitable for complex documents like manuals and books

[Henrik]

Hi all,

There has been discussion in another thread ("Publishing an O'Reilly
book with AsciiDoc") about AsciiDoc's suitability for book type
documents and I thought I share my experience in this area.

I am using AsciiDoc and the docbook toolchain also for quite complex
documents like manuals and must say I consider AsciiDoc well suited
for complex documents. AsciiDoc and the powerful configuration concept
is very versatile and easy to customize.

The combination of AsciiDoc and DocBook allows us the have a
consistent appearance of the documents and to share common text blocks
across numerous manuals. It also helps to focus on content and leave
the styling to the toolchain and the once created style sheets.

We used several other tools before AsciiDoc like Latex and OpenOffice
and found Latex too complex to customize. I found DocBook stylesheets
more consistent and easier to understand through my HTML knowledge
than Latex macros.

The examples below are all created using the 3 components:

- AsciiDoc 8.3.1
- DocBook 1.74.0 XSL style sheets
- FOP 0.94
- Graphics are created using CorelDraw with SVG export or InkScape
with SVG export

User manual example: http://www.proconx.com/gcpmg/UMGCPMG-0801.pdf

Folded installation sheet example: http://www.proconx.com/gcpmg/IGGCPMG-0801-up.pdf
(multipage output created with Multivalent)

Henrik

[Lionel]

Hi Henrik,

thanks for sharing that. These docs look perfect to me, it's a really
good work. I'll never stop to be amazed about AsciiDoc
capabilities... :)

One question I dare to ask: is there a reason to use FOP 0.94 instead
of 0.95? Did you actually tried 0.95? Is there a reason to keep 0.94
or any comments you would accept to share about that topic? FOP
customization is important to get a correct result, and I know that
choosing the fop version is part of this task (for example pdf
bookmarks, fonts customization (I'm a big fan of Palatino Linotype
btw) etc.)

Thanks for sharing your experience, to get this result you must have
spent quite some time refining the toolchain.

Best regards,
Lionel

[Stuart Rackham]

Thanks Henrik, this really is professional stuff, thanks in no small
measure to your customization efforts.

It shows just what can be done with DocBook publishing using Open Source
tools (I suspect many people would not have guessed that this level of
presentational quality was possible this side of becoming a LaTeX guru).

Cheers, Stuart

[Henrik]

> One question I dare to ask: is there a reason to use FOP 0.94 instead
> of 0.95? Did you actually tried 0.95? Is there a reason to keep 0.94

Hi Lionel,

There are indeed good reasons why I settled for FOP 0.94. I tried
several FOP versions, starting from 0.93, 0.94, 0.95beta, 0.95 and SVN
trunk. They all have subtle bugs in certain areas.

I found 0.94 to work best for me as it introduced support for the word
joiner character (unicode #8288) which I required. I use this
character for example to make sure the term "C++" is not hyphenated.

Versions 0.93, 0.94 and 0.95 all have a bug where footnotes in
itemized lists are not correctly processed. This is fixed now in the
trunk.

Versions 0.95 and newer throws on occasion a
java.lang.ArrayIndexOutOfBoundsException. Haven't investigated the
exact cause because I am happy with 0.94.


Henrik

[Henrik]

On Feb 16, 6:33 pm, Stuart Rackham <srack...@gmail.com> wrote:
> Thanks Henrik, this really is professional stuff, thanks in no small
> measure to your customization efforts.

And I have to thank You for producing AsciiDoc, making it open source
and maintaining it.

Henrik

[Lionel]

Hi Henrik,

thanks for your remarks. They are interesting.

regards,
Lionel

[Mark Fernandes]

On Sun, Feb 15, 2009 at 7:21 PM, Henrik <hwm...@gmail.com> wrote:
>
> There has been discussion in another thread ("Publishing an O'Reilly
> book with AsciiDoc") about AsciiDoc's suitability for book type
> documents and I thought I share my experience in this area.
>
> I am using AsciiDoc and the docbook toolchain also for quite complex
> documents like manuals and must say I consider AsciiDoc well suited
> for complex documents. AsciiDoc and the powerful configuration concept
> is very versatile and easy to customize.
>

Hi Henrik,

Very impressive work. Thank you for sharing.

I have a few questions:
- since you know LaTeX, did you try the Asciidoc (unsupported) LaTeX
backend?
- what about dblatex? did you try using that too?
- do you have a particular reason to use FOP for this type of work.

I ask because your work seems to be easier handled with LaTeX rather
than FOP, and given that you know LaTeX both the backend LaTeX
generator and dblatex support would seem a natural fit. I know the
backend LaTeX generator may not have been up-to-date with the current
version of Asciidoc but it works nicely with previous versions.

I look forward to your answers.

Best,

Mark.

[Henrik]

On Feb 16, 11:19 pm, Mark Fernandes <commentedc...@gmail.com> wrote:
> I have a few questions:
> - since you know LaTeX, did you try the Asciidoc (unsupported) LaTeX
>   backend?
> - what about dblatex? did you try using that too?
> - do you have a particular reason to use FOP for this type of work.
>
> I ask because your work seems to be easier handled with LaTeX rather
> than FOP, and given that you know LaTeX both the backend LaTeX
> generator and dblatex support would seem a natural fit. I know the
> backend LaTeX generator may not have been up-to-date with the current
> version of Asciidoc but it works nicely with previous versions.

I worked with Latex a few years ago and I found it very hard to
customize and to style. I spent hours and days loading packages,
searching for documentation and writing customization macros in a hard
to grasp and inconsistent syntax. Compared to Latex, DocBooc XSL is
well structured and has a single point of documentation to reference
(DocBookXSL-TheCompleteGuide). I find DocBooc XSL more productive to
use than Latex.

[Andy68]

As with everyone else, thank you for sharing this document - very
nice. I use the same toolchain (minus the graphics since I just
require basic images) held together with ant.

Would you mind sharing how you organize the source documents? Is it
all in one document or do you have them split up in a hierarchy? I do
the latter. Since my document is quite a bit larger than your's, I
run into problems correlating which source document is behind which
bit of rendered final document.

Again thanks for describing your experience with Asciidoc and this
toolchain.

- Andy

[Noah Slater]

On Thu, Feb 19, 2009 at 03:02:42PM -0800, Andy68 wrote:
> Would you mind sharing how you organize the source documents? Is it
> all in one document or do you have them split up in a hierarchy? I do
> the latter. Since my document is quite a bit larger than your's, I
> run into problems correlating which source document is behind which
> bit of rendered final document.

In case it helps, at O'Reilly we are separating documents by chapter.

Our HTML output is linked together with a custom HTML page.

Our DocBook output is linked together using a base document and XLink.

--
Noah Slater, http://tumbolia.org/nslater

[Andy68]

Ah... great, that is helpful. So you have one document per chapter,
but no top-level document. That might work for me since it would be
easier to pinpoint the source document. I think my subdocument
fragmentation might be a bit excessive. . . Thanks for the reply!

- Andy

[Henrik]

On Feb 20, 9:02 am, Andy68 <andy.jew...@gmail.com> wrote:
> Would you mind sharing how you organize the source documents?  Is it
> all in one document or do you have them split up in a hierarchy?  I do

I have one main document and a large set of subdocuments which I call
"textblocks". This is very similar to a program which uses subroutines
in a library. The "textblocks" are reusable components which are used
in several manuals. For example the description of a RS-232 port pin-
out is used in several manuals or another example would be the usual
safety regulations which are repeated in every manual. Referring to
the manual posted earlier, the chapter Installation in the main
document looks like:

Installation
------------
include::{incdir}/safety_precautions.txt[]
include::{incdir}/regulatory_notes.txt[]
include::{incdir}/unpacking_handling.txt[]
include::{incdir}/before_connecting.txt[]
include::{incdir}/xnut_mounting.txt[]
include::{incdir}/mounting_rules.txt[]

I even use AsciiDoc attributes to parametrize some of the included
textblocks, similar to passing parameters to a function in a
programming language.

Hope that explains a bit the concept. It allows me to quickly create
new manuals with little overhead and also to maintain common text
sections across several product manuals.

Henrik

[Andy68]

Great, thanks, Henrik. Last question. . :) For the final document,
do you piece it together manually
or do you have another top level document that includes chapters in
the same way your chapters included textblocks?

e.g.,

Device FOO Manual
=================
include::{incdir}/chapter1-installation.txt[]
include::{incdir}/chapter2-usage.txt[]
include::{incdir}/chapter3-troubleshooting.txt[]

Many thanks!

-Andy

[Henrik]

On Feb 21, 5:07 am, Andy68 <andy.jew...@gmail.com> wrote:
> Great, thanks, Henrik.  Last question. . :)  For the final document,
> do you piece it together manually
> or do you have another top level document that includes chapters in
> the same way your chapters included textblocks?

I only have a two level hierarchy.

Henrik

[Gabriel Staples]

Your User manual link is broken. Here's the updated link it looks like: https://www.proconx.com/assets/files/products/gcpmg/UMGCPMG-0801.pdf

I'd like to start making manuals, pamphlets, and brochures using something other than LibreOffice, so if you could give me some guides and/or templates that'd be awesome. Meanwhile I'll take a look at your links.

[Lex Trotman]

On Sun, 19 Aug 2018 at 03:07, Gabriel Staples <panth...@gmail.com> wrote:
>
> Your User manual link is broken. Here's the updated link it looks like: https://www.proconx.com/assets/files/products/gcpmg/UMGCPMG-0801.pdf
>
> I'd like to start making manuals, pamphlets, and brochures using something other than LibreOffice, so if you could give me some guides and/or templates that'd be awesome. Meanwhile I'll take a look at your links.
>

If you are just starting with Asciidoc I suggest you should start with
the Asciidoctor (asciidoctor.org) implementation. This is the
original Python 2 implementation which will EOL Jan 2019.

Cheers
Lex

>
>>
>> User manual example: http://www.proconx.com/gcpmg/UMGCPMG-0801.pdf
>>
>> Folded installation sheet example: http://www.proconx.com/gcpmg/IGGCPMG-0801-up.pdf
>> (multipage output created with Multivalent)
>>
>> Henrik
>

> --
> You received this message because you are subscribed to the Google Groups "asciidoc" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to asciidoc+u...@googlegroups.com.
> To post to this group, send email to asci...@googlegroups.com.
> Visit this group at https://groups.google.com/group/asciidoc.
> For more options, visit https://groups.google.com/d/optout.

[Gabriel Staples]

Thanks! I've been looking at asciidoctor for several hours now though, and although I've got a few example .adoc files converting to PDFs, I can't figure out how to make a simple pamphlet. I'd like a single 2-sided 8.5 x 11 inch piece of paper, landscape view, each side with 2 columns, with various text and images and tables and things in specific locations. Any idea how to accomplish such a thing? I need to update this document in a couple dozen fields weekly, so I'd ultimately like to write a Python script to automate the process, since it takes me about 45 min each week to tweak formatting every time when I'd like it to take < 15 min.

[Lex Trotman]

On Sun, 19 Aug 2018 at 07:14, Gabriel Staples <panth...@gmail.com> wrote:
>
> Thanks! I've been looking at asciidoctor for several hours now though, and although I've got a few example .adoc files converting to PDFs, I can't figure out how to make a simple pamphlet. I'd like a single 2-sided 8.5 x 11 inch piece of paper, landscape view, each side with 2 columns, with various text and images and tables and things in specific locations. Any idea how to accomplish such a thing? I need to update this document in a couple dozen fields weekly, so I'd ultimately like to write a Python script to automate the process, since it takes me about 45 min each week to tweak formatting every time when I'd like it to take < 15 min.

Well, probbaly better to ask on the Asciidoctor forums :)

But basically Asciidoc is not a layout markup, the layout is set by
the output toolchain, so CSS for HTML, etc

Cheers
Lex