Re: [HIG] Mini-Guidelines style

[Adam Elman <aelman users sourceforge net>]

At 12:05 PM +0100 8/10/01, colin z robertson wrote:
> 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.

[...]

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

I certainly agree that it'd be easier to transform docbook to 
anything else than to go the other direction; I'm just worried that 
it'll take time for people to learn.  I'm comfortable enough with 
SGML that I'd be happy to learn docbook, so it's up to the rest of 
y'all.

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

Just to keep the structure of the documents a little simpler.  I'd 
reconsider this if there is objection.

>  > Body text should generally be marked simply as <p>;
>
> Please open and close <p> tags. Use them as containers rather than
> separators.

Yes, thank you.

[quotes]
> May I suggest:
>
> <blockquote>
> <p>
> blah blah...
> </p>
> <p class="attribution">
> Some Author
> </p>
> </blockquote>

Again, I don't want to get too bogged down in semantics, and to do 
this _right_ we would need to specify it even clearer than this.  I'd 
rather get this written and published quickly in HTML than in a 
transformable way.

The only structure I think it's important to preserve is structural, 
and that I see us doing through the use of headings.  That will allow 
us to build navigation and a style via CSS.  But I'm open to 
discussion on this. :)

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

I don't particularly, but I don't care a whole lot either way.  If 
there is an official GNOME policy on this I think we should stick to 
it.  I note that the images on the GNOME home page are PNG's, so 
that's probably a good way to go.

Adam
--