Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

DocTeam/DocBook migration/DocBook Design Elements

From TYPO3Wiki
Jump to: navigation, search

notice - This information is outdated

This page contains information about the previously planned migration of the TYPO3 documentation to DocBook. This migration has never been realized; we migrated to reST instead.


Next meeting

  • FR 01.07. at 20:30 Uhr per Skype
  • First draft of layout

Meeting FR 2011-06-10 at 20:30

  • FR 10.6. at 20:30 Uhr per Skype
  • Participants: Sabine, Tom
  • Todo: Design of a document as PDF

Discussed organisatorial issues

Meeting FR 2011-05-27 at 20:30

  • by Skype
  • Attendencies: Tom, Daniel, Sabine
  • Topics: updated structure of the FLOW3 getting started manual, Sorted Elements by priority

TODO for next Meeting

  • DocBook recommendations (toms)
  • Prioritize tags (toms) => Done, see #Sorted Elements by priority
  • Transform FLOW manual (toms)
  • Going through the list of elements (sabine)

Meeting FR 13.5. at 20 Uhr per Skype

We work on these points until next time

  • Liste von Elementen (TS)
    done 2011-04-30; see the complete list of DocBook v5.1 elements (~400) and reduced set for TYPO3 (~200).
    TODO: Discuss the list in the next call.
  • Beispiel Stylesheet (TS)
  • Texte sichten.. (SH)
  • Erstes Design (SH)
  • XML-Mind installieren (SH)
  • Sabine Hueber: Wiki-Dokumentation (DB)

Agenda 2011-05-13

  • List of DocBook elements (ts)
  • Discuss example stylesheet (ts)
  • Presentation of TYPO3 design (Sabine)

Resources

File name
Description
German
DocBook5Tags
The definitive guide - meaning of all  xml-elements
Was bedeuten die XML-Elemente
TomsDocBook5TagsSelection Kleinere Auswahl für uns
GettingStartedSxw
The current Getting Started template
Das aktuelle GettingStarted Vorlage für neue Dokumente
TomsDocBook
Vorschlag von Toms
TSrefSxw


Logo
The TYPO3 Logo as SVG
Das TYPO3 Logo als SVG
TYPO3ShareFont
The official font (licence will be OFL)
Die TYPO3-Schriftart (Lizenz ist OFL-Lizenz)
TomsScreenshots


Git
Git repository Wo liegt die DokBook-Datei
OpenSourceFonts

XML Mind Editor

PrintOnDemand Print on demand provider Dienstleister für DocBook Buch-Druck
FLOW3ManualHTML
FLOW3ManualGit
TomsFlOW3Manual


Fonts

Headlines:

Share Regular

Share Bold

Share Italic

Share Bold-Italic


As bodytext:

Free Sans

Free Mono

List of Elements

A DocBook schema customized for TYPO3 can be found in our Git repository. It is based on the TYPO3 element list (~200).


We have the following categories:

  • Admonitions: caution, important, note, tip, warning
  • Comments: remark
  • Command Elements: arg, cmdsynopsis, command, group, option, parameter, replaceable, type
  • Cross References and Links: xref, link, XLinks
  • Document Structure: appendix, article, book, chapter, glossary, index, preface, reference, refsection, section
  • FAQs: answer, qandadiv, qandaentry, qandaaset, question
  • Function Elements: funcdef, function, funcparams, funcprototype, paramdef, parameter, replaceable, returnvalue, varargs, void
  • Glossary Elements: glossary, glossdef, glossdiv, glossentry, glosssee, glossseealso, glossterm
  • Graphic Elements: equation, figure, imagedata, imageobject, screenshot,
  • Index: indexterm, primary, secondary, tertiary, see, seealso
  • Legal Notices: copyright, legalnotice, trademark
  • Lists: callout, calloutlist, itemizedlist, listitem, orderedlist, procedure, steps, substeps, variablelist, varlistentry
  • Operating Systems: envar, filename, property, systemitem
  • Paragraphs: formalpara, para
  • Programming: classname, constant, exceptionname, funcdef, funcparams, funcprototype, function, interface, interfacename, initializer, methodname, methodparam, modfier, ooclass, ooexception, oointerface, paramdef, returnvalue, tag, structfield, structname, symbol, token, varname, void
  • Reference: refclass, refentry, refentrytitle, reference, refdescriptor, refmeta, refnamediv, refpurpose, refsection
  • Sections: section
  • Tables: colspec, entry, row, spanspec, table, tbody, tfoot, thead, tgroup
  • Titles: subtitle, title, titleabbrev
  • User Interfaces: guibutton, guimenu, keycap, keycombo, menuchoice
  • Verbatim: literal, programlisting, screen, synopsis

Sorted Elements by priority

  1. Root Elements: book, article, reference
  2. Structure Elements: appendix, chapter, glossary, part, preface, refsection, section
  3. Block Elements I: example, figure, all lists, para, procedure, table, programlisting,
  4. Inline Elements I: cross reference, command elements
  5. Block Elements II: admonitions, faqs(?),
  6. Inline Elements II: the rest

Open Questions

  • Is Simple/Simplified DocBook an option?
  • What about bibliographic elements? (add 12 elements)
  • What about mathematical elements?
  • What about tables in tables? Better not support this
  • Which table model: CALS or HTML?
  • What about external schemas like SVG, MathML, ...? Should it be integrated into the TYPO3 customization?

DocBook Layout

The Git repository contains the file manual.xml. To build a PDF, the buildpdf.sh script is used.

Results:

  • Standard layout from the DocBook XSL stylesheets. Only DIN A4 page type is set.
  • TYPO3 layout (work in progress)

TYPO3 Print Specification (TBD)

This small section collects some parameters for the DocBook XSL stylesheets. Please fill in the gaps

  • Page Dimensions: DINA4?
  • Margins:
  • Double page layout or single page layout? printed book=double page; screen=single page
  • Titlepages:
    • Books:
    • Chapters, Appendices, Glossaries:
    • References:
  • Fonts:
    • Titlepage fonts: Share Font
    • Headline fonts (chapters, sections, ...): Share Font(?)
    • Text font (serif font):
    • Code fonts (monospaced):
  • Logos and standard graphics?
  • Special treated Block Elements:
    • Font for title of procedure, figure, table, ...
  • Special treated Inline Elements:
    • remarks: color #FF8000 (orange)
    • links: color #333366 (dark blue)

Does and Don'ts (When Writing DocBook Texts)

This section collects some tips and general markup recommendations to ease the transformation process:

  • Block inside Block:
    Avoid block elements like example inside para
  • Avoid bridgehead