Skip to contentSkip to conversation

Documentation files in html format?

DISCUSSION Bodo Eggert 2 participants 3 messages Aug 9, 2007 2 messages not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

A message that is not in the archive (sent off-list or not yet received): [email protected]

#2 lore raw
Quoted 12 lines · Jan Engelhardt
Quoted 10 lines · Stephen Hemminger

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

Quoted 4 lines
Quoted 2 lines

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.

Quoted 2 lines

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).

Signature · 4 lines
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: [email protected] [email protected]
#3 lore raw
Quoted 3 lines · Bodo Eggert

I don't think <b> and <i> should be used, instead you should use styles (<span class="code"> etc).

<b> does the same as <span style="font-weight: bold;">, and the latter is much more verbose for the same thing.

Quoted 8 lines

Things like <em> and <strong> should be OK, if used consistently.

Quoted 2 lines

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).

Oh that comes because MS Office calls it "Blocksatz" in German ;-)

Jan

#4 lore raw
Quoted 7 lines · Jan Engelhardt
Quoted 2 lines · Bodo Eggert

I don't think <b> and <i> should be used, instead you should use styles (<span class="code"> etc).

<b> does the same as <span style="font-weight: bold;">, and the latter is much more verbose for the same thing.

You shoud use neither. It's OK on homepages, but for documents, you should be able to change the formating using stylesheet.

Quoted 10 lines
Quoted 8 lines

Things like <em> and <strong> should be OK, if used consistently.

Quoted 2 lines

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).

Oh that comes because MS Office calls it "Blocksatz" in German ;-)

I missed that point. What I wanted to say was: If the user overrides ":justify", it would still be called "justified", which would be not justified.-)

Signature · 4 lines
"A slipping gear could let your M203 grenade launcher fire when you
least expect it. That would make you quite unpopular in what's left of
your unit."
-Army's magazine of preventive maintenance.