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:	Fri, 10 Aug 2007 09:40:47 +0200
From:	Sam Ravnborg <sam@...nborg.org>
To:	Andi Kleen <andi@...stfloor.org>
Cc:	Hans-Jürgen Koch <hjk@...utronix.de>,
	Stephen Hemminger <shemminger@...ux-foundation.org>,
	linux-kernel@...r.kernel.org
Subject: Re: Documentation files in html format?

On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
> Hans-Jürgen Koch <hjk@...utronix.de> writes:
> 
> > Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:
> > > Since the network device documentation needs a rewrite, I was thinking
> > > of using basic html format instead of just plain text. 
> > 
> > Why don't you simply use DocBook? Then the user has the choice to convert
> > to HTML, PDF, LaTex or whatever.
> 
> In my experience it tends to be challenging to actually find all the packages
> needed for that. And then it's incredibly slow -- seems to be much slower
> than gcc which is somewhat of an archivement. And at least for LinuxDoc TeX usually 
> can't even compile the result.
> 
> I would say the track record of existing DocBook deployment is not good enough
> to justify further use. Plain html can be converted into all these
> formats easily too and overall it makes a much nicer user experience.
> 
> Also I would expect much more people will know how to write html versus
> DocBook.

Documentation should be easy to access and readable in the source format.
For this purpose asciidoc seems to do a good job.

It is btw. discussed at git ML if they should shift due to toolset being
slow but that happens to be the docbook utilities. asciidoc seems to be fast enough.
And it can produce both HTML and docbook so seems to cover all cases.

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

Powered by blists - more mailing lists