clayts / docscii Goto Github PK

Please add support for the simplesect DocBook element (which is something we use a lot in the JBoss Fuse library). The simplesect element can be processed almost identically to a regular section element. But I would like the converted simplesect to be annotated with metadata to ensure that it can be converted back into a simplesect element when it is processed by ccutil.
In other words, I would like the following DocBook sample:

<simplesect xml:id="Sample-ID">
  <title>Sample Heading</title>
  ...
</simplesect>

To convert to:

[simplesect]
[[Sample-ID]]
===== Sample Heading

Where the number of equal signs above obviously depends on the current level of indentation.
I tested this AsciiDoc snippet and found that it gives back exactly the original DocBook shown above, when you convert it using asciidoctor -b docbook <filename> (which is what ccutil does when building the book).
The big advantage of this (from our perspective) is that the Red Hat docs toolchain currently supports simplesect in its CSS stylesheets, so our books will look much nicer if we preserve this metadata.

This switch would tell docscii to preserve as custom tags all tags not otherwise translated (i.e. throw away nothing).

The (C), (R), and (TM) symbols were not converted properly in a DocBook containing them that was converted from publican format.

Need to treat header cells and ordinary cells differently, because we need to use a special syntax to enable AsciiDoc formatting inside an ordinary cell. To use AsciiDoc formatting, you need to delimit the cell by starting with a| and ending with a newline, \n. In other words, instead of formating a table like this:

|===
|Header 1|Header 2|

|Foo|Bar
|===

It should be formatted like this:

|===
|Header 1|Header 2|

a|Foo
a|Bar

|===

And then it becomes possible to put fancy formatting inside the table cell (lists, code listings, etc.)

One of the eccentricities of the JBoss Fuse library is that we use olink elements a lot, not only for linking within a book, but also for linking between different books in the same library. Now, these are different cases, so I will go through them separately.

First, using olink to define a link to an element in the same book. Here is an example of this olink syntax:

<olink targetptr="TargetID"/>

Which can easily be rendered in AsciiDoc as:

<<TargetID>>

Second, using olink to define a link to an element in a different book in the same library. Well, we don't really have a proper solution for this case at the moment (thought it will probably be solved soon in the context of Docs 2.0). My strategy to deal with this kind of olink is to preserve the metadata through the conversion to AsciiDoc and then deal with it later. Here is an example of this olinksyntax:

<olink targetdoc="TargetBookID" targetptr="TargetID"/>

I suggest converting it to AsciiDoc as follows:

link:olink:TargetBookID/TargetID[]

This is legal AsciiDoc syntax, but will not be processed, since olink: is an unknown scheme. This would give me a handy placeholder which I can search and replace some time in the future, when we have worked out a more permanent solution.

When converting a DocBook containing a URL with a " " in it, the URL was not rendered correctly. trying to account for this may not be possible but I'm logging it as an issue to let you know

Two goals:

1. make it obvious what translations will occur for various tags and make it easy to change
2. make it easier to add custom preserved tags without having to recompile

This will require that the tag translations in translate.go be refactored out.

DocBook supports tables in both CALS and HTML formats. Currently, docscii supports only CALS format, but we use both table formats in our Fuse library.

Line breaks when converting from publican to asciidocs are created with a single '+' at the beginning of the line, instead of '\s+' which asciidocs can't render correctly and which breaks references within the next paragraph

In DocBook 5, it is possible (in fact, recommended) to define ordinary HTTP hyperlinks using the following syntax:

<link xl:href="http://foo">Optional Text for Link</link>

Where xl references the xlink Namespace URI. This can be rendered easily enough in AsciiDoc as:

http://foo[Optional Text for Link]