Re: Documentation files in html format?

[Jan Engelhardt <jengelh@computergmbh.de>]

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@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/