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.
| File name/URL | File size | Date submitted | |
|---|---|---|---|
| markup.txt | 4.2 KB | January 09 2013 02:29 UTC | |
| analysis.sh | 1.1 KB | January 09 2013 02:29 UTC | |
| markup2.txt | 4.2 KB | January 10 2013 01:17 UTC | |
| markup3.txt | 4.7 KB | January 10 2013 01:41 UTC |
I would like to work on this task.
The claim on this task has been removed, someone else can claim it now.
I would like to work on this task.
This task has been assigned to Monika. You have 72 hours to complete this task, good luck!
Hello. How is it going? The task is more difficult than it looks like (as usual). We'd like to know if you already have some ideas how to solve this task. Do not hesitate to ask questions.
Melange has detected that the initial deadline has passed and it has set the task status to ActionNeeded. The student has 24 hours to submit the work before the task is reopened and sent back to the pool for other students to claim.
Hi, the deadline passed. Do you still want to work on this task? If so, please tell us, such that we can extend the deadline, or get in touch with us via IRC.
Melange has detected that the final deadline has passed and it has reopened the task.
I would like to work on this task.
This task has been assigned to Matthew. You have 72 hours to complete this task, good luck!
The work on this task is ready to be reviewed.
Thank you, the result is great, exactly what we expexted.
However, could you please put in the first table with the macros their actual usage, such that you don't have to know mdoc to parse the table? E.g. that Nm prints the name, Xr is a reference, etc.
And maybe also their actual rendering as done by man (eg references are underlined, names are underlined, arguments are printed bold, etc.
If you do so, this task is complete.
Ok, this looks great. You could make the analysis.sh a bit prettier, but this doesn't matter. Thank you!
Congratulations, this task has been completed successfully.