The Roqet Document Format

Prelude

I used to store all the quick-reference documentation that I put together in simple text-files; this was so that I could access them remotely via the command-line, and so that they would be small enough to carry around or email.

Then I started putting together these online document pages so that I (and others) could access them from a web browser. Of course they needed to look a little prettier than simple text, so I had to reformat them. Being a somewhat lazy programmer, the manual reformatting became a burden, so I wrote a Perl script RoqDocBuild that could convert them for me. However, the script was not accurate enough in guessing what needed to be a link, code, heading, etc. so I added a few indicators to my simple text to tell the script how to reformat it. The result of this is the Roqet Document Format. Both the RoqWiki (that was used to create this site) and RoqetPad (from version 6.0) use this format too.

You may be wondering why I didn't use one of the many document formats out there (like one of my favorites, POD)? Basically, the formats I came across weren't very readable as a text file, or couldn't have code as part of the text (which I needed for my command-lists). So I did what any programmer does when software doesn't meet their needs; I created my own.

---

Roqet Document Format v2.1

- = comment
@ = heading
*** = bullet(new style)
*-* = horizontal line
[code block] = code block
{{link~~link text}} = hyperlink
{*image_filename*} = image link
command = explanation = converts to command: explanation
[[ = indicates start of preformatted block (becomes a <pre> tag)
]] = indicates end of preformatted block (becomes a </pre> tag)
-->import:filename = indicates place to import an external file into a <pre></pre> tag block

Example

-= A Small Example =-

- this is a small example file using Roqet Document Format

@ basic commands
----------------
adduser = adds a new user (must be root)
alias = adds aliases for commands [alias foo=ls]
apropos = gives an idea what command to use [apropos image]
at = schedule a one-time job [at 8am 3/31/02] followed by [echo "test time!" | mail -s "reminder" dominic] and the [ctrl-d], this will schedule an email "reminder".
link = this is a link example: {{http://www.roqet.org/software.html~~Link Example}}
[[
a line of preformatted text
]]
{*screenshot.jpg*}
-->import:myfile.txt

Suggestion

As a reminder to yourself and others, consider putting this comment block somewhere near the top of your file:

- this document is formatted in Roqet Document Format v2.1 which can easily be
- converted to html using the RoqDocBuild which is available here:
- http://www.roqet.org/software.html
- The Roqet Document Format is as follows:
- - (comment)
- @ heading (heading)
- *** bullet
- *-* horizontal line
- command = description and [examples] (descriptive line)
- [code block]
- {{link~~link text}}
- {*image_filename*}
- [[
- preformatted block (puts in <pre></pre> tag block)
- ]]
-->import:filename to import an external file into <pre></pre> tag block