Re: Documentation files in html format?

[Bodo Eggert <7eggert@gmx.de>]

Jan Engelhardt <jengelh@computergmbh.de> wrote:
> On Aug 9 2007 11:31, Stephen Hemminger wrote:

>>Since the network device documentation needs a rewrite, I was thinking
>>of using basic html format instead of just plain text. But since this would
>>be starting an new precedent for kernel documentation, some it seemed
>>like a worthwhile topic for discussion.
>>
>>Advantages of html:
>>  * basic formatting like lists, italics, etc
>>  * easier to integrate into other places and retain formatting
>>  * ability to link documents and to external sources easier
>>
>>Downsides:
>>  * can become too formatted and unclear
> 
> So only use <h1> to <h6>, <p>, <b>, <i>, <u>, <ul>, <ol> and <li>.

I don't think <b> and <i> should be used, instead you should use styles
(<span class="code"> etc). Things like <em> and <strong> should be OK,
if used consistently.

> Perhaps maybe <p class="block"> with .block{text-align:justify;}
> because that looks nice in general.

If you like that, you can say "p {text-align:justify;}" in the default
stylesheet. (And if people would override the alignment, class="block"
would be the wrong name).


BTW: You should not listen to those "frames-are-evil" guys. This will only
force you to include all the navigation code in each page, and having to scroll
beyond a ton of navigation stuff was a major annoyance while trying to read
the selinux docs. Instead, you should e.g. provide an "up", "prev" and "next"
link on each page, and keep the rest in the navigation frame (if needed).
-- 
Top 100 things you don't want the sysadmin to say:
0. I just made an extra 2 meg of space in /,  I stripped /vmunix.
    Oh, so that's why ps doesn't work.
Friß, Spammer: ZJCnAN@mBlrwf80.7eggert.dyndns.org An4grd@Z.7eggert.dyndns.org