Re: [HIG] Mini-Guidelines style

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

> 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:

blah blah...
<p class="attribution">
Some Author

> 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?


  _____________________________                            ____
  rtnl     c z robertson ndirect co uk
                                                   icq 13294163

Attachment: pgp36iBFztJl7.pgp
Description: PGP signature

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]