linux-kernel - Re: Documentation files in html format?

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <E1IJ7DO-0000pI-JN@be1.lrz>
Date:	Thu, 09 Aug 2007 14:34:10 +0200
From:	Bodo Eggert <7eggert@....de>
To:	Jan Engelhardt <jengelh@...putergmbh.de>,
	Stephen Hemminger <shemminger@...ux-foundation.org>,
	linux-kernel@...r.kernel.org
Subject: Re: Documentation files in html format?

Jan Engelhardt <jengelh@...putergmbh.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@...rwf80.7eggert.dyndns.org An4grd@...eggert.dyndns.org
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/