[Firebird-docs] [FirebirdSQL/firebird-documentation] 86161a: Converted fbcache-de to AsciiDoc. Corrected some t...
Branch: refs/heads/master Home: https://github.com/FirebirdSQL/firebird-documentation Commit: 86161a3d073b61c162276df3423fc777aa25dc33 https://github.com/FirebirdSQL/firebird-documentation/commit/86161a3d073b61c162276df3423fc777aa25dc33 Author: Martin Köditz Date: 2020-05-27 (Wed, 27 May 2020) Changed paths: A src/docs/asciidoc/de/firebirddocs/fbcache/firebird-fbcache.adoc Log Message: --- Converted fbcache-de to AsciiDoc. Corrected some typos. ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] First 'new' documents online
On 2020-05-27 08:37, Köditz wrote: Hi Mark, well, I misunderstood the document's structure. I just looked for the switch 'asciidocHtml' which already creates some kind of 'chunked' document. In the docbuilding howto you can only see 'docbookHtml'. But now I know how to work with it. The docbuilding howto also documents asciidocHtml: https://firebirdsql.org/file/documentation/html/en/firebirddocs/docbuildhowto/firebird-docbuilding-howto.html#docbuildhowto-building-output-docs However, that doesn't produce chunked output. Since I already have CMS access I should be able to publish the docs by myself. Otherwise I will call for help. Ok, that is fine. However, there is more necessary than just publishing the new docs: I also need to coordinate with Sergey to add redirects from the old documents to the new documents (if only so bookmarks and published links elsewhere will continue to work and point to the new docs). So if you publish new documents, let me know which, so I can set this up. Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
[Firebird-docs] The single Page for the documentation outline
Hello All, As you know, Firebird documentation contains a set of documents, and they are grouped in several pages, by the topic or type of documents, like Release Notes, etc. Should we consider build the overall list of the docs and put to the Documentation starting Page? It would be like a big outline. Not like a 100% organized documentation set, of co3, but better than current distributed structure. What do you think? Regards, Alexey Kovyazin ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
[Firebird-docs] Conversion of fbcache-de
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. 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 If you like I can also convert the English version. Regards Martin ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] The single Page for the documentation outline
> Hello All, > > As you know, Firebird documentation contains a set of documents, and they are > grouped in > several pages, by the topic or type of documents, like Release Notes, etc. > > Should we consider build the overall list of the docs and put to the > Documentation starting Page? > > It would be like a big outline. Not like a 100% organized documentation set, > of co3, but better than current distributed structure. > > What do you think? > > Regards, > Alexey Kovyazin Hi Alexey, do suggest some kind of big TOC? Yes, I would prefer it. Regards Martin ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] The single Page for the documentation outline
Hello Alexey, > As you know, Firebird documentation contains a set of documents, and they > are grouped in several pages, by the topic or type of documents, like > Release Notes, etc. > > Should we consider build the overall list of the docs and put to the > Documentation starting Page? Absolutely. I never liked the way it is now. Before the move we had the index on one page, with several category headers, which worked fine. Furthermore, we saved huge amounts of vertical space by using one table row per document, putting the (English) name in the first column and the links to the various language versions in columns 2 and 3, like this: [Name column] | HTML | PDF/other 1.5 Quick Start Guide | en fr de pt | en fr de pt 2.0 Quick Start Guide | en de es pt | en de es pt ... Worked perfectly, all on one page, with as little scrolling as possible. Cheers, Paul ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] The single Page for the documentation outline
On 2020-05-27 09:43, Alexey Kovyazin (ak) wrote: Hello All, As you know, Firebird documentation contains a set of documents, and they are grouped in several pages, by the topic or type of documents, like Release Notes, etc. Should we consider build the overall list of the docs and put to the Documentation starting Page? It would be like a big outline. Not like a 100% organized documentation set, of co3, but better than current distributed structure. What do you think? I'm not sure what you mean. This sounds like what we already have at https://firebirdsql.org/en/firebird-rdbms/, that page and its subpages is that list as I see it. Mark ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] The single Page for the documentation outline
Hello Mark, Like that Page but with high level table of contents for each document. Regards, Alexey Kovyazin ср, 27 мая 2020 г., 14:25 Mark Rotteveel : > On 2020-05-27 09:43, Alexey Kovyazin (ak) wrote: > > Hello All, > > > > As you know, Firebird documentation contains a set of documents, and > > they are grouped in several pages, by the topic or type of documents, > > like Release Notes, etc. > > > > Should we consider build the overall list of the docs and put to the > > Documentation starting Page? > > > > It would be like a big outline. Not like a 100% organized > > documentation set, of co3, but better than current distributed > > structure. > > > > What do you think? > > I'm not sure what you mean. This sounds like what we already have at > https://firebirdsql.org/en/firebird-rdbms/, that page and its subpages > is that list as I see it. > > Mark > > > ___ > 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] The single Page for the documentation outline
Hello Alexey, I didn't understand at first that that's what you wanted. A high-level ToC for each document on the doc index page doesn't seem useful to me and only clutters the page. I think everbody knows what they can expect from: - Release Notes - Quick Start Guide - Firebird Language Reference - Nbackup guide - Firebird's isql Interactive SQL tool etc. The per-document ToC only becomes interesting if you already decided that you need that document. And then you'll open it anyway. Cheers, Paul > Hello Mark, > > Like that Page but with high level table of contents for each document. > > Regards, > Alexey Kovyazin > > > ??, 27 ??? 2020 ?., 14:25 Mark Rotteveel : > > > On 2020-05-27 09:43, Alexey Kovyazin (ak) wrote: > > > Hello All, > > > > > > As you know, Firebird documentation contains a set of documents, and > > > they are grouped in several pages, by the topic or type of documents, > > > like Release Notes, etc. > > > > > > Should we consider build the overall list of the docs and put to the > > > Documentation starting Page? > > > > > > It would be like a big outline. Not like a 100% organized > > > documentation set, of co3, but better than current distributed > > > structure. > > > > > > What do you think? > > > > I'm not sure what you mean. This sounds like what we already have at > > https://firebirdsql.org/en/firebird-rdbms/, that page and its subpages > > is that list as I see it. > > > > Mark > > > > > > ___ > > 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
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
