[Firebird-docs] Translators: Changes to Docbuilding & Docwriting Howtos

[Paul V. <pa...@vi...>]

Hello translators.

Here are the changes to the Docbuilding and Docwriting Howtos. These
two articles live together in the <book> "Documentation for Firebird
Docwriters".


Affected files:
  firebirddocs.xml
  fb-docwriters-info.xml (new file)
  docbuilding-howto.xml
  docwriting-howto.xml


*** Please don't forget to do a "cvs update" of the original
*** English docs before updating your translation.


(1)
In firebirddocs.xml:

Line added:
  <!ENTITY fb-docwriters-info SYSTEM
    "file:../docs/firebirddocs/fb-docwriters-info.xml">

Lines removed:
  <book id="firebird-docwriters-info">
    ...
  </book>

Lines added:
  <!-- Firebird docwriters' info book -->
  &fb-docwriters-info;

The point here is that the <book> has now been placed in a file
of its own, to keep firebirddocs.xml small.


(2)
fb-docwriters-info.xml:

This is the new file, which you should copy to your language directory
and translate.


(3)
In docbuilding-howto.xml:

- <title> changed
- <edition> added

- Section "Do I really have to build the docs myself?":
  Text changed; order of URLs changed.

- Section "How to set up the environment for the build":
  Changed "envvar" -> "envar"
  (matter of taste, you don't have to follow this).

- Section "Building the HTML and PDF docs":
  Changed some "\" to "/" (also matter of taste; you decide).
  Text in Note replaced by itemizedlist with 2 items.
  Last sentence ("If you want to write...") changed.

- Appendix A: Document History added.

- Appendix B: License notice added.
  You should add a Contributor's Section to the license notice to
  claim and date your translation. More about this in the (renewed)
  Firebird Docwriting Guide.


(4)
In docwriting-howto.xml:

- <title> changed
- <edition> added

- Section "Purpose of this Howto":
  "Howto" --> "guide" in section title and text.

- Section "Assumed knowledge":
  "Howto" --> "guide"

- Section "Topics discussed in this Howto":
  "Howto" --> "guide" in section title and text.
  Text/listitems changed in *last two* itemizedlists.

- Section "Picking a subject":
  4th listitem: "...very well" --> "...a lot about" (taste again).

- Section "DocBook XML - an introduction":
  The comment "To be added: a note for people..." has been
  replaced with a <note>.

- Section "Tags and attributes":
  2nd para past the <table>: "valid XML" --> "well-formed XML", and
  an explanation added.

- Section "Special characters and Entities":
  "...although that's not necessary" --> "...but you don't have to"
  (taste).
  Last word before "Elements" header: "Howto" --> "guide".

- Section "A DocBook XML primer":
  "a DocBook document should be" --> "a valid DocBook document is".

- Section "Benefits of DocBook XML":
  Removed one listitem and reworked the text of the others.

- Section "DocBook XML authoring tools":
  4th para: "Howto" -> "guide".

- Section "Creating the document":
  Changed a lot of  "<element>'s" plurals to "<element>s" (dropped
  the apostrophe). Of course it depends on the rules of *your*
  language if you follow this (maybe you never included them in the
  first place...).

- Section "Elements we use frequently":
  In the <tip>: "Howto" -> "guide".

- Section "Hierarchical elements":
  In the <note>: "Howto" -> "guide".

  Also, in this *and* the following sections on elements, I changed
  a lot of <sgmltag class="starttag"> to <sgmltag class="element">.
  The latter is more correct, but the effect is that the element name
  is now shown as e.g. just "book" instead of "<book>". You decide.

  In the itemizedlist after the long programlisting, just before the
  "Lists" subsection header, an extra sentence has been added to the
  3rd listitem.

- Section "Lists":
  First line changed.
  Programlisting itemizedlist: spacing="compact" added.
  Itemizedlist: Para added about spacing attribute.
  Orderedlist: Almost everything changed.
  New varlistentry: procedure (with the example listitems that were
  previously in the orderedlist example).
  Variablelist: Changed paras before and after the programlisting.

- Section "Links":
  Link: Changed "-" to ";" in first para. Wow!
  Link: Changed first sentence after programlisting, dropped all
  the "advanced" stuff, and added a <blockquote>, a <caution> and a
  <note> instead.
  Xref: entirely deleted.
  Ulink: changed programlisting + following para; added blockquote.
  Email: first para: line -> piece; para after programlisting changed
  into para + blockquote; changed last words of <warning>.
  Anchor: changed last para.

- Section "Program listings, screens, literal layout, and examples":
  Programlisting: last line of first para: "Howto" --> "guide", and
  replaced "." with ":". Added example programlisting + <important>.
  Literallayout: "Howto" --> "guide" in the <note> at the end.

- Section "Tables":
  One-but-last paragraph, shortly before Admonitions header: sentence
  "(This is...)" removed.

- Section "Various inline elements":
  filename - command - application - envar:
    para "The output reads:..." split into para + blockquote.
    para "This is rendered as:..." split into para + blockquote.
  superscript - subscript: changed first line.
  sgmltag: first para: "Howto" --> "guide".
  One-but-last para, shortly before "To wrap up the elements" header:
  removed "of course".

- Section "To wrap up the elements":
  Last few words: "Howto" --> "guide".

- Section "Style":
  Last listitem: "Or don't you think so???" --> "Don't you agree???"

- Section "Copyrights of others":
  Title changed to "Respecting others' copyrights".
  First para (towards the end): "illegal" now wrapped in <emphasis>.

- Section "Your copyright":
  Title changed to "Your copyright and the PDL".
  Section text almost completely replaced, and 4 subsections added
  (lots and lots of text).

- Section "Using PostgreSQL docs":
  Para "The most recent PostgreSQL license..." and subsequent ulink
  (both link text and url attribute!) changed.

- Appendix A: Document History added.

- Appendix B: License notice added.
  You should add a Contributors Section to the license notice to
  claim and date your translation.


Good luck!

More to come (but probably not today).


Greetings,
Paul Vinkenoog