asciidoctor-fopub

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

asciidoctor-fopub

1marc1
Hi Team,

I am starting to play around with asciidoctor-fopub. I have created a custom docbook-xsl directory and was able to register the fonts that I want to use. So far, so good. Now, my asciidoctor source file contains a part where I don't want the sections to be numbered. It doesn't matter if I use:

:numbered!:
== Test section
Text, text, text.
:numbered:

or if I use:

:sectnums!:
== Test section
Text, text, text.
:sectnums:

In both cases the fopub generated PDF file will contain section numbers. If I generate the file with asciidoctor-pdf, then (in both cases), the sections are not numbered.

A second question I have is: how do I get rid of the "Chapter" bit that is placed in front of each new chapter? I have been searching the internet and have come up with answers like:

http://docbook.10921.n7.nabble.com/problem-with-customizing-header-td13303.html

...however I wouldn't know how or where to implement this.

Thank you for your suggestions.

Marc.

and have two questions:

Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Hi, I'm very interested in both your questions. But before I touch on them, please let me ask you:

Do you think chapter-/section-numbering (and any generated text that accompanies it) should be managed at the point of AsciiDoc's transformation to DocBook (e.g., by setting :sectnums: etc.) or at the point of DocBook XSL (and any such packagings of it as asciidoctor-fopub)?

On reflection, I think this is the more fundamental question that your topic brings out so helpfully. In my short time messing with AsciiDoc, I've failed to notice any great consensus on the question (and indeed, your two questions betray a bit of ambivalence: Your first question seems to lean towards the AsciiDoc-based management; but your second wants to clean up what's happening at the XSL end).

I'm grateful for your topic for pointing me to this important, basic question. For like you, I'm trying to get my DocBook ducks in a row (pun probably intended ;).

Having wrestled with it now, for a couple of reasons I'm leaning towards management at the AsciiDoc end of things:

1. As illustrated by your first question, I feel there's what us old electrical engineers call (metaphorically) an impedance mismatch, when trying to get AsciiDoc to control the section-numbering through the DocBook XSL (via things like XML processing-instructions inserted by Asciidoctor). Things just don't seem to hang together too well--and it just feels awkward and unwieldy to try to get them to work. (I'm intentionally omitting the relevant technical aspects of XSL here.)

By the way, I think Asciidoctor has, it seems, almost hung back from getting too down and dirty with this approach. But I find that quite understandable: part of the impedance mismatch lies in the problematic question that won't go away: "Which of them are we supposing is really in charge of this??"

2. If we control from AsciiDoc the section-/chapter-numbering for our use of Asciidoctor's HTML backend, wouldn't it be in line with the "write once, publish everywhere" philosophy of the whole thing, if those same attributes we use for HTML would control the numbering for our use of Asciidoctor's DocBook backends?

Now, I believe just as sure as I'm sitting here that with an appropriate Asciidoctor extension, all such numbering can be controlled from that end, using just the standard attributes (:sectnums:, :sectnumlevels:, :leveloffset:, :doctype:). It would insert the numbering right into the section-/chapter-title elements, and then when using DocBook XSL, one would just disable its numbering of sections and chapters (by setting the relevant parameters to 0).

But, having chewed on the bone a while, let me throw it back to you (sorry for the icky metaphor): At which end, in your opinion, should all this numbering be managed? Or, shall we do it at both ends, and just hope they don't step on each other too much?

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

1marc1
Andy,

That is quite a response. To answer your question, I think it should work like this:

1. Create a (source) file
2. Specify what the output should look like for the specific output type (e.g. PDF, HTML5, DocBook, ePub, etc)
3. Generate the output.

If we are using asciidoctor-pdf in step 3, then we have a great tool to use in step 2: the asciidoctor-pdf theme.
Asciidoctor-fopub uses DocBook as a source, therefore our step 3 will need to generate DocBook output first, before the three step process can be repeated. Again, the creation of the DocBook output (during the first cycle) should honor the output directives we provide during step 2 (i.e. asciidoctor mark-up). Equally, the creation of - say - PDF output from a DocBook source should honor the output directives of step 2 (i.e. XSL styles).

Given that DocBook itself is a source for creation of various output formats, it should therefore respect its own formatting directives.

Before posting my two questions, I looked for methods to accomplish my goal; initially by looking at the asciidoctor side and then by looking at the next level: DocBook.

It would be great if someone could point me in the right direction.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Excellent, lucid--and patient--reply. Thanks! And yes, one needs to know what the technological options, and pros and cons, are for doing some thing (e.g., section-numbering) in this or that iteration of the cycle, when both iterations support it.

Of course, I haven't really proven my boldish claim that a proper Asciidoctor extension could do all this numbering from the AsciiDoc end--i.e., in the first iteration of your lucidly-explained "cycle". But I can now offer a "proof of concept" for that, I believe.

To unpack that: I think an Asciidoctor extension could do all that (as far as I'm aware) DocBook XSL can do, regarding section-/chapter-numbering; and yet, it could also do what AsciiDoc can do additionally: turn numbering on and off, and do level-offsetting. In addition, such an extension could do different numbering styles at different levels--producing, for example, the section-number '1.A.c'. (DocBook XSL can do differing numbering styles, BUT it does not appear to me that it can change numbering-styles between levels.)

So, the "proof of concept" I've got is an extension that does all the above--except for the Roman-numeral numbering styles that DocBook XSL will do. The reason I've not included the latter is that I can't be bothered (having no personal need for Roman numerals). The code I've got convinces me, though, that one could add it pretty easily.

Furthermore, the extension provides these configuration-variables (whose values you can change), for control over the numbering (please ignore the '_sntp' suffix on each variable name, which is just poor-man's namespacing):

`
$punct_sntp = '.'         # punctuation between levels' numbers: e.g., '.' yields '1.3.2'
$nr_suffix_sntp = '. '    # punctuation after the number and before the chapter's/section's title
$chap_nums_sntp = true    # enables/disables chapter-numbering
$chap_nr_prefix_sntp = 'Chapter '
$sec_nr_prefix_sntp = ''
# The style you want at each level (first level is chapters; each level's style must be 'A', 'a', or '1'):
$styles_arr_sntp = [ '1', '1', '1', '1', '1', '1', '1', '1', '1', '1' ]
`

If you're comfortable using extensions (instructions for which are at https://github.com/asciidoctor/asciidoctor-extensions-lab#using-an-extension ), I could send you this, so you can play around with it.

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
This post was updated on .
P.S. OH! I remembered another functionality the DocBook XSL has, and which I therefore needed to add--and have now added, along with this additional configuration variable:

$chap_nr_in_sec_nr_sntp = true   # in book, starts sec-labels' nrs with chapter's number (whether or not chap-labeling enabled)

BTW, how did you embed code with code-style (monospace), in your message? I don't get it!!

Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
P.S.S. In full-disclosure mode, I suppose I'd have to admit that I found DocBook XSL has more-fine-grained control than AsciiDoc does over PART-numbering, in a book with multiple Parts (over and above the chapters).

In fact, I don't see any automatic Part-numbering support mentioned for AsciiDoc at all. But personally, I'm okey-fine with that. If you wanna write books with lots of parts, though, I guess you'd want to consider whether automated numbering with DocBook stylesheets isn't more your cup of tea.

Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
P.P.P.S. But I don't see, on second thought, any reason you couldn't use the DocBook XSL for Parts-numbering, if you need such, and the extension for the chapter- and section-numbering.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

1marc1
Andy,

Possibly like others reading this thread, I am keen to see the extension you have created.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Marc,

The 2 Ruby files, along with the sample.adoc and the change to README.adoc needed for adding this extension to the AsciiDoctor Extensions Lab (on GitHub), are in a Pull Request to do so, and are thus publicly visible:

https://github.com/asciidoctor/asciidoctor-extensions-lab/pull/90/files

However, I was going to email you a zip-file of the extension (you deserve special treatment, since it was your discussion-topic that inspired the extension!). But the discussion-forum email system didn't offer any way to attach a file

The name of the extension's registration-file is "section-numbers-tree-processor.rb". Before using it, please read the introductory comment in that file.

If you find any issues, or ways to improve it (even Roman numerals!), please let me know. You can feel free to bring them up in this thread.

Cheers,
Andy

P.S. It's OK to include the extension even when converting to non-DocBook: The extension checks first to see what Asciidoctor backend you're using; if it's non-DocBook, the extension inserts nothing (no numbering) into the output.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

mojavelinux
Administrator
In reply to this post by Andrew Carver
I don't see any automatic Part-numbering support mentioned for AsciiDoc at all.

This was added in the upcoming 1.5.7 release. See https://github.com/asciidoctor/asciidoctor/issues/2298

Cheers,

-Dan

On Tue, May 1, 2018 at 7:46 PM, Andrew Carver [via Asciidoctor :: Discussion] <[hidden email]> wrote:
P.S.S. In full-disclosure mode, I suppose I'd have to admit that I found DocBook XSL has more-fine-grained control than AsciiDoc does over PART-numbering, in a book with multiple Parts (over and above the chapters).

In fact, I don't see any automatic Part-numbering support mentioned for AsciiDoc at all. But personally, I'm okey-fine with that. If you wanna write books with lots of parts, though, I guess you'd want to consider whether automated numbering with DocBook stylesheets isn't more your cup of tea.

Andy


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/asciidoctor-fopub-tp6285p6290.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Superb! And thanks for the heads up, Dan.

In this Issue resolution, will block.level 1 still be the chapters? (In which case, may we infer that parts will be block.level 0?)

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
P.S. OH -- how about a much more interesting question:

Does the Issue resolution include some assumption--or else some control--over whether chapter-numbers restart in each new Part?

e.g.,
http://docbook.sourceforge.net/release/xsl/1.75.2/doc/fo/labels.html

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
P.P.S. Sorry, I meant this link, to the more-specific topic:

http://docbook.sourceforge.net/release/xsl/1.75.2/doc/fo/label.from.part.html
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

1marc1
In reply to this post by Andrew Carver
Andy,

I haven't played around with extensions before, but this will be the perfect opportunity to do so.

Thank you.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Hi Marc,

You bet! But as soon as you update to Asciidoctor 1.5.7 (which is just available), please retrieve the latest version of the files--which I've just now uploaded.

This update to the extension works with the previous Asciidoctor version(s?) too, but it takes advantage of the Parts-numbering feature that Dan added in 1.5.7. BUT NOTE, if you use it with pre-1.5.7, you might need to comment-out the ':partnums:' line at the top of sample.adoc!

Enjoy!

Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
Marc,

FWIW, I've added support for Roman numerals; it seems that Part-nrs are frequently in this format.

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
This post was updated on .
In reply to this post by 1marc1
Hi Marc,

I spaced it totally--and shamefully--on answering your second original question:

1marc1 wrote
A second question I have is: how do I get rid of the "Chapter" bit that is placed in front of each new chapter? I have been searching the internet and have come up with answers like:

http://docbook.10921.n7.nabble.com/problem-with-customizing-header-td13303.html

...however I wouldn't know how or where to implement this.

Thank you for your suggestions.

Marc.
Since your first question revealed that you'd already made a copy of asciidoctor-fopub's "docbook-xsl" folder (to do a customization of it), I think the only other piece of info you need for this is that that the file described in http://www.sagehill.net/docbookxsl/CustomGentext.html#CustomGenText as "your entire customization layer file", into which the suggested snippet of XSLT needs inserting, is in fact docbook-xsl/fo-pdf.xsl.

So, you'd need to insert that snippet (from http://docbook.10921.n7.nabble.com/problem-with-customizing-header-td13303.html ), into that XSL file's `<xsl:stylesheet>`, root element, as a top-level child of it. A reasonable place would be just after the line `<xsl:param name="fop1.extensions">1</xsl:param>
` (approx. line 27).

Since your original question was about fopub, I guess I'd thought my section-numbering extension pretty much answered the issues you were having. But, if you're also planning on publishing on, say, the HTML side of things, and especially if your content involves an index that would need auto-generating, then my extension is not necessarily the wonderful solution to all life's problems :o

For in DocBook XSL's HTML stylesheet, the auto-indexing (in autoidx.xsl) will reference section-titles, in lieu of (the non-existent) page numbers; and thus it will grab as well the section-numbers that my extension has prepended to those titles. That would make even more awkward, an HTML-indexing approach that was already awkward at best (IMHO). One's alternatives would be:

1) to use DocBook XSL's auto-labeling, instead of my section-numbering extension;

2) wait for Asciidoctor's HTML backend to support auto-indexing (see Issue #450), and hope that when it happens, it will be customizable enough for your indexing needs;

3) continue to use my extension, and depend on your (or someone else's) XSLT-customization skills to implement some different, less awkward HTML-index-content-model you like (see, e.g., some ideas being floated at Issue #450).

Thanks, I've enjoyed our discussion! Please extend it with any other comments or questions that bubble up.

Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

1marc1
Andy,

I have spent a good few hours reading up on such things as Apache FOP and Docbook XSL. I have been trying to get my head around how asciidoctor-fopub fits in with these projects. I have been searching through the
build/fopub/docbook
 directory structure inside asciidoctor-fopub. I have also been re-reading this entire message thread (a few times).

In the end, I have managed to get rid of the "Chapter" bit in my chapters, by following exactly what you said in your last message.

It is actually starting to make more sense now. I still haven't had a chance to look at your extension, well... I looked at it, but haven't done anything with it yet because I first need to read up on how to use the extensions and it has gotten late.

I have been using http://www.sagehill.net/docbookxsl/ a lot to find out more about all the contexts, parameters, attributes sets and attributes. I also came across http://doccookbook.sourceforge.net/html/en/DoCookBook.html, which looks like an interesting read.

It is all a bit dazzling at the moment. Perhaps a silly (bunch of) questions (forgive me if the terminology is wrong), but for me to get rid of the "Chapter" bit in my PDF output, I updated the customization layer for Docbook XSL in a file called "fo-pdf.xsl". In there, I updated the "chapter" template which resides inside the "title-numbered" context.

1. How could I have known the existence of this context and the template?
2. I have been searching on the sagehill.net website I mentioned above (which seems very comprehensive), but I am having a hard time finding this context - and therefore what other settings can be made inside this context. A Google search like this
"title-numbered" site:sagehill.net
 doesn't return specifically what I am looking for or expect to find.
3. If this context is called "title-numbered", then are there other, similar contexts such as "title-not-numbered"?

Thank you.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

Andrew Carver
This post was updated on .
Hi Marc,

I appreciate these excellent questions. Also, thanks for the reference to the DoCookBook.

So, after casting about some, finally I scrolled up and read the first part of the page at http://www.sagehill.net/docbookxsl/CustomGentext.html. It appears that, for each natural language that DocBook XSL supports, there is an XML file that contains all the default "generated text", including any "contexts" and so on. 

These files are in the "common" folder in the DocBook XSL distribution. Thus, for English, the XML file containing this data you'll find at asciidoctor-fopub/build/fopub/docbook/common/en.xml .

For example, you'll see at line 351 your "title-numbered" context. And just above it, starting at line 337, there's one for "title-unnumbered".

Thanks for asking me this, so I could learn it! :D
Cheers,
Andy
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-fopub

1marc1
Andrew,

After having thought about it more, the answer to my questions is: learn how the structure of internal files works and what those files provide.

Thank you for your prompt reply!

Marc.
12