Re: [Firebird-docs] Conversion of fbcache-de
On 27-05-2020 10:57, Köditz, Martin wrote: 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. https://firebirdsql.org/file/documentation/html/de/firebirddocs/fbcache/firebird-fbcache-de.html https://firebirdsql.org/file/documentation/pdf/de/firebirddocs/fbcache/firebird-fbcache-de.pdf I hadn't noticed it before, but the names of these files don't match the standard output of the build. The intent is for it to be possible to upload the build output without having to manually rename files. So to produce the right output, the German AsciiDoc file should match the intended output filename (for the names above, `firebird-fbcache-de.adoc`). We may want to consider tweaking the filenames further (eg to `firebird-cache` for English and `firebird-cache-de` for German), this avoids the repetition of `firebird` and its abbreviation `fb`. See also the suggested naming conventions at https://firebirdsql.org/file/documentation/html/en/firebirddocs/docwritehowto/firebird-docwriting-guide.html#docwritehowto-asciidoc-file-naming-convention Mark -- Mark Rotteveel ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
On 28-05-2020 12:01, Köditz, Martin wrote: You're right. The CMS is back again. So I updated the German and English fbcache docs. Please have a look. Looks good to me. Mark -- Mark Rotteveel ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
On 2020-05-28 12:01, Köditz wrote: On 2020-05-28 10:35, Köditz wrote: Hi Mark, thank you for the feedback. I did the conversion with help of Pandoc. Pandoc is not my tool of choice for the conversion. I have selected Docbookrx and implemented a number of customizations for it. For the sake of consistency of output, I think it is better >that a single method of conversion is used. I will correct it. Now I know what to look for. Thanks. Mark Well, I tried to use Docbookrx, but got some errors. I will try it again later. Did you use the one from the firebird-modifications branch of https://github.com/mrotteveel/docbookrx ? Yes, I used the modified one. I have to find out what the problem is. I know it doesn't run directly on Windows (or at least, I believe I had some issue with Ruby, and I switched to my Ubuntu WSL shell immediately). Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
>On 2020-05-28 10:35, Köditz wrote: Hi Mark, thank you for the feedback. I did the conversion with help of Pandoc. >>> >>> Pandoc is not my tool of choice for the conversion. I have selected >>> Docbookrx and implemented a number of customizations for it. For the >>> sake of consistency of output, I think it is better >that a single >>> method of conversion is used. >>> I will correct it. Now I know what to look for. >>> >>> Thanks. >>> >>> Mark >> >> Well, I tried to use Docbookrx, but got some errors. I will try it >> again later. > >Did you use the one from the firebird-modifications branch of >https://github.com/mrotteveel/docbookrx ? Yes, I used the modified one. I have to find out what the problem is. > >If you're working on Windows, I would recommend running it from within a WSL >shell (eg Ubuntu from the Windows store). > >> I corrected the AsciiDoc source. The output looks much better now. >> >> Is the CMS currently down? I can't access it. > >It seems to be up again right now, though I didn't login (I don't have the >credentials on my work laptop). > >Mark You're right. The CMS is back again. So I updated the German and English fbcache docs. Please have a look. Martin ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
>> Hi Mark, >> >> thank you for the feedback. I did the conversion with help of Pandoc. > >Pandoc is not my tool of choice for the conversion. I have selected Docbookrx >and implemented a number of customizations for it. For the sake of consistency >of output, I think it is better >that a single method of conversion is used. > >> I will correct it. Now I know what to look for. > >Thanks. > >Mark Well, I tried to use Docbookrx, but got some errors. I will try it again later. I corrected the AsciiDoc source. The output looks much better now. Is the CMS currently down? I can't access it. Regards Martin ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
On 2020-05-28 08:38, Köditz wrote: Hi Mark, thank you for the feedback. I did the conversion with help of Pandoc. Pandoc is not my tool of choice for the conversion. I have selected Docbookrx and implemented a number of customizations for it. For the sake of consistency of output, I think it is better that a single method of conversion is used. I will correct it. Now I know what to look for. Thanks. Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
Hi Mark,
thank you for the feedback. I did the conversion with help of Pandoc. I will
correct it. Now I know what to look for.
Can we put an example excerpt in the docwriting howto? I think that would help
any translator. And we will get a uniform structure.
Regards
Martin
-Ursprüngliche Nachricht-
Von: Mark Rotteveel [mailto:m...@lawinegevaar.nl]
Gesendet: Mittwoch, 27. Mai 2020 20:33
An: firebird-docs@lists.sourceforge.net
Betreff: Re: [Firebird-docs] Conversion of fbcache-de
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:
[] [] ['<''>']
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 `.` 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
___
Firebird-docs mailing list
Firebird-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Conversion of fbcache-de
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:
[] [] ['<''>']
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 `.` 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
