On 27-05-2020 10:57, Köditz, Martin wrote:
Hello,
this is for your information.
I converted my first doc to asciiDoc: fbcache-de. I think everything is
fine. I already uploaded the PDF and the HTML output.
Please feel free to give me some feedback.
In general, it looks good to me. I have three remarks.
1) The syntax of the author list of asciidoc does not formally support
comments like `(deutsche Übersetzung)` in
```
Norman Dunbar; Martin Köditz (deutsche Übersetzung)
```
The syntax is something like:
<firstname> [<middlename>] [<lastname>] ['<'<emailaddress>'>']
As a result, the parser now considers `Martin Köditz (deutsche
Übersetzung)` entirely as firstname (insert the {firstname_2} attribute
in a document to see this). I would recommend just leaving the
`(deutsche Übersetzung)` part out, and optionally add a preface before
`toc::[]` to clarify.
3) Don't forget to add yourself to the fbcache-license section. See also:
-
https://www.firebirdsql.org/file/documentation/html/en/firebirddocs/docwritehowto/firebird-docwriting-guide.html#docwritehowto-asciidoc-copyrights-translator
-
https://www.firebirdsql.org/file/documentation/html/en/firebirddocs/docwritehowto/firebird-docwriting-guide.html#docwritehowto-copyrights-pdl-howto
3) I noticed an oddity in the transformation in section
fbcache-mon-io-stats. The title of the formalpara of the xml should have
been transformed as `.MONS$STAT_ID`, but it is now `*MONS$STAT_ID.*`.
Did you manually change that?
The `.<text>` is the general way to add titles to objects (in this case
to a paragraph), and is the equivalent of formalpara in the old XML when
before a parapgraph. Just using bold emphasis as a replacement in such a
a usecase is the 'wrong' semantic information.
As an improvement I would recommend to use a description list[1] for this.
[1]: https://asciidoctor.org/docs/user-manual/#description-list
For example
```
*MONS$STAT_ID.*
Die Statistik-ID.
*MONS$STAT_GROUP.*
Die statistische Gruppe. Statistiken werden in folgende Gruppen unterteilt:
* 0: Die Datenbank als Ganzes.
* ...
```
Would then change to
```
MONS$STAT_ID::
Die Statistik-ID.
MONS$STAT_GROUP::
Die statistische Gruppe.
Statistiken werden in folgende Gruppen unterteilt:
+
* 0: Die Datenbank als Ganzes.
* ...
```
(use `+` to 'link' following paragraphs or other blocks to the same
listitem).
https://firebirdsql.org/file/documentation/html/de/firebirddocs/fbcache/firebird-fbcache-de.html
The title images were missing. I have fixed this by uploading the images
folder of the build output (build/docs/asciidoc/html/de/images) to
file/documentation/html/de.
https://firebirdsql.org/file/documentation/pdf/de/firebirddocs/fbcache/firebird-fbcache-de.pdf
If you like I can also convert the English version.
If you have the time, that would be appreciated. Thanks!
I will ask Sergey to add redirects this weekend.
Mark
--
Mark Rotteveel
_______________________________________________
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
