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-prev] [thread-next>] [day] [month] [year] [list]

Date:	Thu, 9 Aug 2007 12:49:41 +0200 (CEST)
From:	Jan Engelhardt <jengelh@...putergmbh.de>
To:	Stephen Hemminger <shemminger@...ux-foundation.org>
cc:	linux-kernel@...r.kernel.org
Subject: Re: Documentation files in html format?

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

>  * accessibility and translation issues?

Accessibility, well, just run w3m instead of less, and you've got it.
Or `w3m -dump xxx.html | less` if you really need it paged.

Translation, no I do not think that is a big issue. But people should
perhaps be kept on the utf-8 toe since html can specify the encoding.

>  * even more style issues

- two lines between block elements, e.g.
  <h1></h1>\n\n<p></p>\n\n<ol></ol>\n\n..

- tabs used, <ol>\t<li>long long text\n\t\twrapped line</li>\n</ol>

There is not much to it I think. Use of WYSIWYG editors should be prohibited,
since some reformat the code in terms of line length, "aol-ize" it
(<ol> to <OL>) or replace tags by some synonym.

	Jan
-- 
-
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/