OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Recursive use of elements <option> and <optional>


as far as I understand the migration from db4 to db5 the definition and content model of "technical inline elements" (%tech.char.class; ?) changed significant. I want to add some comments to their *recursive* use - not to the other aspects of this elements.


In db4 it was able to use <function> ("Function -- The name of a function or subroutine, as in a programming language") recursively. In db5 this is no longer possible. I appreciate this change as a function name is an atomic construct and cannot contain other function names.

The same applies to <literal> ("Literal -- Inline text that is some literal value").

In db4 it was possible to use <literal> as a subelement of <function> and vice versa. In db5 this is no longer possible. I have seen some situations in our documentation, but they don't make sense and shall be modified by manual intervention.


In db4 it was possible to use <option> and <optional> recusively: <option> within <option> or <option> within <optional> and vice versa. This makes sense as it reflects the real situation of computer languages. In db5 this is no longer valid. As long as there is no other technique to express such computer language situations we need the recursivity as it was defined in db4.

In db4 it was possible to use <function> as a subelement of <parameter>. This is no longer possible in db5. Also <funcsynopsis> is not valid within <parameter>. Especially for functional languages like Scala it is natural to use functions as parameters. Therefore the db4 semantic makes sense.

In summary the content model of all IT related elements shall be reviewed:
  • Which elements are really atomic?
  • Which elements may contain which other elements, especially elements of the same kind?

Kind regards
Jürgen Purtz

On 21.06.2016 07:58, Jürgen Purtz wrote:
In docbook 4.x it was possible to use <optional> in a recursive way, eg: https://www.postgresql.org/docs/current/static/sql-createtable.html or https://www.postgresql.org/docs/current/static/sql-select.html. Optional elements often are only valid under the additional demand, that they are part of another optional element. The same holds true for arguments of commands or procedures.

We try to upgrade to docbook 5.x, but the schema doesn't allow the recursive use of <option> and <optional>. Do you have an advice how to express such situations? Do you have plans to modify the docbook 5 schema to allow recursive use of the two elements?

Kind Regards
Jürgen Purtz

To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]