[Welcome to Sensei's Library!]

StartingPoints
ReferenceSection
About


Paths
EditableRGGFAQ
EditableRGGFAQPart4
EditableRGGFAQPart1
EditableRGGFAQPart2
EditableRGGFAQPart3
EditableRGGFAQPart5
EditableRGGFAQPart6
EditableRGGFAQPart8
EditableRGGFAQPart9

Referenced by
RGGFAQ
RGGFAQPart1
RGGFAQPart4
RGGFAQPart5
RGGFAQPart1Section7
RGGFAQPart3
RGGFAQPart1Section4
RGGFAQPart6Section1
RGGFAQPart2
RGGFAQPart6
RGGFAQPart6Section2
RGGFAQPart2Section1
RGGFAQPart2Section2
RGGFAQPart3Section1
RGGFAQPart4Section9
RGGFAQPart3Section3
RGGFAQPart8
RGGFAQPart3Section2
RGGFAQPart1Section5
RGGFAQPart4Section2

 

RGG FAQ Format Guidelines
    Keywords: Question

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 [ext] 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...



This is a copy of the living page "RGG FAQ Format Guidelines" at Sensei's Library.
(OC) 2004 the Authors, published under the OpenContent License V1.0.