Hi,
converting to Markdown is easy, but there are some things underspecified
(e.g., how to reference commands). Call me a nitpicker, but this is a style
guide I roughly thought about. I don't want to enforce it for anyone, just
hear some comments.
Regards, Julian
# Style guide for NetBSD documentation
Markdown is a very liberal language in what range of input it accepts,
rendering all the same output although looking very different.
This is a proposal how to write NetBSD documentation. It is not necessary to
strictly adhere it, but for the sake of unity and readability, the last two
sections about *Code and keywords* and *Referencing manpages* should be read.
# Using lists
Lists should be indented by a space, an asterisk, and a space again. Text on
that list level should then continue with three spaces indented.
Deeper list levels should continue the same pattern, just starting with the
indentation. I.e., second-level lists should be started by four spaces, then
an asterisk, then a space; following lines should be indented by six spaces,
etc.
Bad:
* structures
* files
* sockets
Good:
* structures
* files
* sockets
For numbered lists, you should try to keep the numbering right, even when
only in textmode. You indent each level by four characters, with the list
item being started by a space, a `1.`, and a space. For numbered lists with
more than nine elements, drop the space in the beginning, i.e. do a `10.`,
then a space, then the item.
Bad:
1. Introduction
1. Welcome
Good:
1. Introduction
2. Welcome
# Using headers
Put either one or two whitelines before a header, depending on the importance
of the header (rough: two lines for first and second level, one whiteline for
everything below).
Don't use setext headers, only ATX headers. I.e., not the ones which have a
line of dashes or equals signs following, but only the ones which have a
single line, started by hash signs. Don't put hash signs at the end of a
header.
Bad:
Chapter 1. Introduction
================
Good:
# Chapter 1. Introduction
Don't use special characters in a header - it should consist only of
alphanumeric characters.
Bad:
# The file `/etc/hosts`
Good:
# The file /etc/hosts
# Image captions
When you place an image in an article, separate it into its own paragraph.
Make a linebreak, then place in bold letters the caption of the image.
Bad:
Then you see the welcome screen:
**Welcome screen*
After pressing the *Home* button, you will get to..
Good (notice two spaces after the image line):
Then you see the welcome screen:
**Welcome screen*
After pressing the *Home* button, you will get to...
# Referencing manpages
Reference manpages once per section, i.e. write them down in NAME(SECTION)
notation:
sh(1)
After that, don't write the commands in monospace or italic, only when you
want people explicitly to call them. See below for further information.
# Code and keywords
When displaying code, indent it by four spaces, not more - only when it is
part of the code (i.e., indentation).
Bad:
int main(int argc, char *argv[]) {
return 0;
}
Good:
int main(int argc, char *argv[]) {
return 0;
}
When asking a user to execute a command, do this by putting the text into
single quotes (or, when quotes are part of the text, more):
Bad:
Now, we have to **restore -i**, to get back the information.
Good:
Now, we have to `restore -i`, to get back the information.
For more important or longer commands, put them in a single code environment
indented by four spaces. Each command line should be prepended by a hash sign
and a space.
Bad:
Now, we have to `openssl enc -pass 12345 | tar -c -f file.tgz`.
Good:
Now, we have to do
# openssl enc -pass 12345 | tar -c -f file.tgz
When referencing a command without asking the user to execute it, just leave
it untouched - many commands are then used as verbs themselves, and putting
them separately would look strange. Only do this if you referenced it before
as a manpage.
Bad:
Now, you have to **tar** the file, then pass it to `openssl` to decrypt.
Good:
Now, you have to tar the file, then pass it to openssl to decrypt.
Attachment:
signature.asc
Description: PGP signature