For Experienced Writers, New To KDE

Useful tips

• Use an SGML-aware editor. It will just save you so much time (e.g. you won't have to look up the structure any more in the documenation, the editor will not allow invalid markup, and you'll have to learn much less). If you use Emacs, then there is the psgml-mode (1.2.1).

• For often repeated sequences, like the name of an application, use general entities. In the case of the application, the conversion has added a definition for an entity with the name of the application. So that

      <para><application>KAbc</application> learns people to write
      Sanskrit and <application>KAbc</application> is very good at
      it.</para>
  

  can be written as

      <para>&kabc; teaches people to write Sanskrit and &kabc; is very good
      at it.</para>
  

  Much less error-prone, certain to be consistent, faster to type and to read. Don't exaggerate however. You can for instance add a ulink to refer to the application home page, but all occurrences of the name will become links then (which is not very pretty). Don't do it with "KDE", since the header already contains a link.

• To know what the result might look like: read the processing expectations in the DocBook reference pages. You can rely on that - everything else may change.

• Do NOT, and this is very important, do NOT use physical markup, but mark only up according to the content. With an example: do NOT use <literal>foo.txt</literal> but <filename>foo.txt</filename>, because there is the element for it. How do you find out: the Quick Reference in the DocBook Reference documentation (Appendix G) is a _very_ handy tool to answer such questions.

• You may say, after looking through the Quick Reference: "I want this in courier, but I cannot find how to do it" (or worse, "so I'll use the element <literal>"). In that case, ask yourself a different question: "Why do I want this in courier?". For instance, "because it's a constant". Perfect: use the <constant> element then. There are over 300 elements, so you should nearly always find something. If in doubt, ask the kde-docbook mailing list.

  If you don't find how to mark something up, please don't just take anything that will look similar! We'd much prefer that you don't mark it up at all, rather than that you use knowingly the wrong markup!

• For more information, examples and a full description what you can do: consult the DocBook reference documentation. In case of problems: kde-doc-english@kde.org.

Emacs

Emacs users can do the following for the date:

Local Variables:
time-stamp-format:"%02y-%02m-%04d"
time-stamp-line-limit:100
time-stamp-start:"<date>"
time-stamp-end:"</date>"
End:

And the time-stamp will set the date in the correct format.

As for the SGML requirements, most of them can be obtained in Emacs with psgml with the following settings (which can be added to the local variable section above):

sgml-namecase-general: t
sgml-namecase-entity: nil
sgml-general-insert-case: lower
sgml-omittag: nil
sgml-minimize-attributes: nil

With these settings, "Normalize" (from the Modify entry in the psgml menu) will produce the correct effect in a few seconds.

For the rest:

• to replace an entity: C-c C-=
• to add an attribute: C-c C-+ (with completion)
• to add an element: C-c C-e (with completion)

See also the psgml menu) for more

If you're not using Emacs, then you'll have to live with less support. We hope that will improve soon though.