RGG FAQ Format Guidelines
All the FAQ pages on SL are of course normal SL pages and standard SL formatting rules applies.
However, the FAQ should be thought of as a separate entity to SL and be kept as a USENET FAQ type. This means that:
- We will have to accept duplicating content between the FAQ and SL. (I.e. we cannot just refer the FAQ section on shape to the SL page on the same)
- The overall size of the FAQ should not increase dramatically. Less is more. (I accept that already, the FAQ is too voluminous in many cases...)
- Judging by comments/questions I have received, the FAQ is predominantly read by beginners. Please keep this in mind.
Furthermore, in addition to being 'just' SL pages, the pages are also used to create a single-file FAQ which is posted on the newsgroup rec.games.go, so there are two more reasons which imply some restrictions on the formatting:
- A script which should not be too complicated should be able to parse the files.
- The finished text should look good on ascii-only newsreaders.
I therefore propose the following 'restrictions' on standard SL:
- Links will be translated as follows: text within the first part of the link (in front of the '|' (if any) will be quoted verbatim, followed by the insertion of the word 'at' and followed by the URL. This means that the sentence around the link should be formulated to make this readable. E.g. "Check out Sensei's Library for .." will become ascii-fied to "Check out Sensei's Library at http://senseis.xmp.net/?Frontpage for ...". Sometimes this means that the sentence around may need to be formulated slightly different from what seems natural.
- To avoid confusing internal (to the FAQ) links with those external to the FAQ, refer to other FAQ sections as [Section x.y|RGGFAQ_x_y]. (I.e. the string "Section 0-9+\.0-9+\|" will be treated as links internal to the FAQ.)
- Bold/underline markup cannot be reflected in the ascii version and will be ignored.
- Leave one empty line between each line of text.
- Lists will work as usual.
- Indentation (e.g. the address list) is made through the use of colon/semicolon.
- Diagrams will lose their title
- Add new subjects on the RGGFAQ_Partx pages and add them to the contents list on RGGFAQ
- Include header and footer on new pages similar to the existing ones
I think that this is all.
I have a fairly good notion of how I want the script to work, but I have not yet coded a word... so we may need to change these or add some to make the whole system run smoothly.
If you have any suggestions, this is the place for them...