On Thu, Aug 09, 2001 at 03:33:51PM -0700, Adam Elman wrote: > [Note: I'm choosing HTML here rather than docbook or anything else > because I know how to write HTML, and I think if we stick to the > below instructions, it'll be fairly straightforward to transform the > HTML into other formats as needed. I don't want us to get bogged > down in learning docbook or anything like that just to write the > mini-guidelines; we're on too short a timeline. 'Course, if I'm the > only person who doesn't know how to write docbook, then I think I can > pick it up pretty quickly. Again, though, I think it's more > important for us to get the content written in a consistent way and > we can figure out how to transform it later.) Personally, I'd go for docbook. It's easier to convert from docbook to html than vice-versa. Html to docbook will require some degree of manual work. What do other people think? Are other people familiar with docbook? If we do go for html I have a few more recommendations to make... > Topics under these subsections should be marked as <h3>. No headers > below <h3> should be present. Why not? > <h3>Always show keyboard shortcuts</h3> > > Body text should generally be marked simply as <p>; Please open and close <p> tags. Use them as containers rather than separators. > Any quotes or paraphrases from other documents should be noted. I > would recommend using a simple scheme for this like (Cooper, 1999) > and having a single bibliography, but if anyone has a particular > favorite reference style I don't feel strongly about it. Lengthy > direct quotes from other documents, books, etc. should be marked as > <blockquote> and noted. May I suggest: <blockquote> <p> blah blah... </p> <p class="attribution"> Some Author </p> </blockquote> > Inline images (screenshots, etc.) should be included on their own > paragraphs. The ALT text should include a brief description of the > image. We may want to add figure captions inline in the text later. > Do not include image formatting instructions, except height/width. > Inline images should always be local; don't refer directly to an > image on another site. Do we want to be PNG purists here? colin _____________________________ ____ rtnl http://rational.cjb.net c z robertson ndirect co uk icq 13294163
Attachment:
pgp36iBFztJl7.pgp
Description: PGP signature