Implement conditions

[tradej]

In DocBook, almost any element can be conditional, i. e. displayed/evaluated only when a condition is defined. Our team uses these conditions extensively, as we have several sources that vary only in product names and such, so this is a key feature for us.

A few notes:

• Most of the time, we use something like <phrase conditon="FOO">bar</phrase> or <chapter condition="BAZ">...</chapter>, in general nested as needed. I understand that, for example, this construct:

  <title>
    Foo <phrase condition="BAR">baz</phrase> qux
  </title>

  is probably not easily convertible as both titles and conditions in AsciiDoc require the line to start with = or ifdef, respectively, and that the XML source will have to be modified to be convertible.

• It is not important for us if one-line or block conditions are used in the resulting document. Both:

  ifdef::FOO[bar]

  and

  ifdef::FOO[]
  bar
  endif::FOO[]

  are okay.

• <xi:include ...> statements in DocBook also support conditions, but that can easily lead to invalid XML documents, which are buildable by Publican (that happens by including multiple tags with the same ID, for example). I am not sure if conditional inclusion should be supported for this reason.

[junaruga]

Hi, @mojavelinux

I heard from @tradej 's colleague right now about the background of this suggestion. We are working in same kind of team.

The background of it, is they are managing their XML files to publish their HTML documents right now. And then they are converting from their XML files to HTML files by one tool: publican [1], if they need to public the documents. The source XML files has the condition statement (condition="FOO"). I guess that it may be specified feature for publican [2].

However they want to change their way to manage AsciiDoc files to publish their HTML files in the future. And they want to convert from their XML files with condition to AsciiDoc files with condition [3] at once. Then they want to convert from the AsciiDoc files to HTML files by your product: asciidoctor, if they need.

Is there a possibility to implement this? Though the "condition" tag may be specified for one tool publican.

[1]: publican web site: https://fedorahosted.org/publican/ [2]: publican condition feature in XML: https://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/chap-Publican-Users_Guide-Creating_a_document.html#sect-Publican-Users_Guide-Conditional_tagging [3]: AsciiDoc format has condition statement: 21.3.2. Conditional Inclusion Macros http://asciidoc.org/userguide.html#_system_macros

Thanks for your reading this.

[mrietveld]

Hi @junaruga ,

I'm pretty sure I speak for @mojavelinux if I say that all improvements are welcomed, as long as they follow both the docbook and asciidoc specifications.

I don't think we can functionality to docbookrx that doesn't relate to the docbook specification -- the whole purpose of the tool is to convert docbook to asciidoc.

The "condition" tag that you mention sounds a lot like docbook conditionals.

[tradej]

Hi, an update: @junaruga is going forward with implementing the conditionals. The only caveat that we know is that if there is a character directly following the condition (e. g. a comma, period, semicolon, etc.), it has a space before it. This behaviour will be documented.

[junaruga]

Hi, @mrietveld I sent pull-request to asciidoctor/docbookrx master branch. I would like you to merge this to the master branch.

Though I sent pull-request to your repo: mrietveld/docbookrx development branch last time, I would like you to throw away its modification for the development branch, because I updated my code after that. Sorry for that! Thanks.

[mojavelinux]

I am in support of converting conditionals in DocBook to AsciiDoc preprocessor conditionals. As it has been stated, AsciiDoc implements conditionals at the line level using preprocessor directives. This allows conditionals within a paragraph if the phrase is split across multiple lines:

Foo
ifdef::BAR[baz]
qux

If the conditional is in the middle of a title (section or block title), then the whole line has to be repeated:

ifdef::BAR[.Foo baz qux]
ifndef::BAR[.Foo qux]

The preprocessor conditionals fit most naturally with block-level elements, which naturally stand alone in the document.

For more fine-grained inline conditionals, there is a "pick" extension incubating in the extensions lab. If we decide that there are cases that line-level directives can't handle, then we should probably be looking at using this macro. See https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/pick-inline-macro.rb.

---

One major difference between AsciiDoc and DocBook is when these conditionals are processed. In AsciiDoc, they are handled before the structure of the document is read. In DocBook, the conditionals are stored in the AST. Down the road, I anticipate having conditions per node that are stored in the AST, but we aren't there yet.