Logged-In As
ACCOUNT
Not Logged In
Investigate necessary documentation markup The NetBSD Project
Status: Closed Time to complete: 72 hrs Mentors: Radoslaw Kujawa, Julian Coleman, Julian Fagir Tags: research, overview

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.

Uploaded Work
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
Comments
Katelin Huber on December 10 2012 12:51 UTC Task Claimed

I would like to work on this task.

Katelin Huber on December 10 2012 12:53 UTC Claim Removed

The claim on this task has been removed, someone else can claim it now.

Monika on December 12 2012 05:27 UTC Task Claimed

I would like to work on this task.

S.P.Zeidler on December 12 2012 08:25 UTC Task Assigned

This task has been assigned to Monika. You have 72 hours to complete this task, good luck!

Radoslaw Kujawa on December 13 2012 21:47 UTC Progress?

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 on December 15 2012 08:25 UTC Initial Deadline passed

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.

Julian Fagir on December 15 2012 17:01 UTC How is is going?

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 on December 16 2012 08:25 UTC Task Reopened

Melange has detected that the final deadline has passed and it has reopened the task.

Matthew on January 7 2013 22:31 UTC Task Claimed

I would like to work on this task.

Julian Fagir on January 7 2013 22:41 UTC Task Assigned

This task has been assigned to Matthew. You have 72 hours to complete this task, good luck!

Matthew on January 9 2013 02:30 UTC Ready for review

The work on this task is ready to be reviewed.

Julian Fagir on January 10 2013 00:38 UTC Already very great

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. 

Julian Fagir on January 10 2013 14:27 UTC Thank you!

Ok, this looks great. You could make the analysis.sh a bit prettier, but this doesn't matter. Thank you!

Julian Fagir on January 10 2013 14:27 UTC Task Closed

Congratulations, this task has been completed successfully.