GSoC/GCI Archive
Google Code-in 2012 The NetBSD Project

Investigate necessary documentation markup

completed by: Matthew

mentors: Radoslaw Kujawa, Julian Coleman, Julian Fagir

To choose the right markup language for documentation, you need a clear and comprehensive list of needed markup. While formats like Docbook or Latex support nearly everything, languages like Markdown or RestructuredText are more limited and have different dialects.


Your task is to investigate which formats are needed for documentation (links, blockquotes for code, tables, monospace font, headlines in different sizes, etc.) and specify those.
Formats like Docbook and mdoc are also providing semantical information, i.e. though they may display everything the same, e.g. the document knows whether a given monospace font written object is a filename, a command name, a function call, etc. Thus you also have to investigate whether these formats are used, and if their usage makes sense.


In the end, you should provide a table of needed markup formats and of currently used semantical content of manpages, and whether they are in use somewhere.

Our preferred format for the submission is some form of plain text, as that is most portable and can be read anywhere.  If you want to use a word processor, please export the file as text.  You could also add something like markdown or latex to add structure (these are both plain text based), but that is not a requirement.