DocTeam/Restructuring migrated manuals
All existing official manuals were migrated from OpenOffice to ReStructured Text. Although the automation went well, human care is needed to make the manuals really usable in ReST. Below is a checklist of things to do:
Possible with a script
Martin has written a script, which can do the following things:
- main include: copy the "Includes.txt" file from the Official Manual Example project, include it at the top of every ReST file and clean up the top of each ReST file.
- spaces: the exact indentation of lines is important. But trailing spaces and spaces in empty lines can be removed.
- update conf.py and add the generic Settings.yml file.
Human work needed
- rendering date: add the
construct in the meta data of the manual.
- review the folder names: during the migration, the OpenOffice documents were split on the level 3 headings. Each such heading gave its name to a folder, inside which is an Index.rst file. There are two aspects to review here:
- the splitting may have gone too far. If the Index.rst file contains very little content, it should probably be merged with the preceding "chapter".
- the name of the folder is not always very good. The folder name will appear in the URLs of the documentation, so it can often be made shorter while staying explicit.
- add labels: all sections must have labels so that we can link to them. Labels must be unique within the same manual. They should be explicit but not too long. In particular a "start" label must be added at the beginning of each manual. Example:
.. _start: ================= Official Template =================
- tables: when migrating from OpenOffice, all tables were changed to use the ".. container:: table-row" directive. This is then rendered as a definition list in HTML. While this is good for TypoScript or TSconfig reference, it is often not appropriate for other tables, which should stay as tables. In such a case, any table format available in ReST is fine to use, but the "t3-field-list-table" directive is particularly suited.
- quotes: replace smart quotes with simple quotes.
- images: images were all extracted from the OpenOffice files and given automated names. Two things must be done here:
- rename the images to some meaningful name
- in the ReST source, replace all uses of "|img-xx|" substitutions by the use of the "figure" directive. Example:
paragraph with some text. .. figure:: ../../Images/ExtensionConfigurationOptions.png :alt: Configuration screen for the rsaauth extension next paragraph with more text...
- Settings.yml: Update the manual name, the years and the version numbers.
Examples of all these constructs can be found in the example manual and in (at the time of this writing) the "Extension Architecture" chapter of Core APIs (see https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi).