Documentation files in html format?

Documentation files in html format?

[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

Downsides:
  * can become too formatted and unclear
  * accessibility and translation issues?
  * even more style issues

Re: Documentation files in html format?

[Jan Engelhardt]

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

Re: Documentation files in html format?

[Hans-Jürgen Koch]

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.

Thanks,
Hans

Re: Documentation files in html format?

[Stephen Hemminger]

On Thu, 9 Aug 2007 15:08:20 +0200
Hans-Jürgen Koch <hjk@linutronix.de> wrote:

> 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.
> 
> Thanks,
> Hans

That's probably how I'll go, but there is surrounding text.

Re: Documentation files in html format?

[Andi Kleen]

Hans-Jürgen Koch <hjk@linutronix.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.

-Andi

Re: Documentation files in html format?

[Rene Herman]

On 08/09/2007 05:26 PM, Andi Kleen wrote:

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

ACKACKACKACKACKACKACKACKACKACKACK.

Rene.

Re: Documentation files in html format?

[Jarek Poplawski]

On 09-08-2007 17:26, Andi Kleen wrote:
> Hans-Jürgen Koch <hjk@linutronix.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.

In case of some counting: my vote is for Andi! 

Down with DocBook!!! Go txt!!! Go html!!! Andi for president!!!

Jarek P.

Re: Documentation files in html format?

[Francois Romieu]

Andi Kleen <andi@firstfloor.org> :
[...]
> 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.

xsltproc converts from docbook to html fast enough (PDF with a docbook
Java/fop toolchain is a different story). Your experience is a bit
outdated.

> Also I would expect much more people will know how to write html versus
> DocBook.

Yes, it is easy to write more or less random html. I'd even prefer plain
utf8 text.

-- 
Ueimor

Re: Documentation files in html format?

[Andi Kleen]

> xsltproc converts from docbook to html fast enough (PDF with a docbook

I don't think that is used by Linuxdoc. Try a make pdfdocs and see
for yourself.

-Andi

Re: Documentation files in html format?

[Francois Romieu]

Andi Kleen <andi@firstfloor.org> :
[...]
> I don't think that is used by Linuxdoc. Try a make pdfdocs and see
> for yourself.

It reminds me of an old PII but it does not really make clear how
html to pdf conversion would improve the situation.

-- 
Ueimor

Re: Documentation files in html format?

[Rene Herman]

On 08/10/2007 12:27 AM, Francois Romieu wrote:

> Andi Kleen <andi@firstfloor.org> :
> [...]

>> I don't think that is used by Linuxdoc. Try a make pdfdocs and see for
>> yourself.
> 
> It reminds me of an old PII but it does not really make clear how html to
> pdf conversion would improve the situation.

With HTML the source format is itself the preferred object format for many 
purposes (something which I assume you wouldn't want to claim of DocBook 
source) meaning that for those uses there is no conversion.

Which given the number of times "make *docs" has bombed out on me through 
the years I find a definite improvement. Add in that it's much easier to 
produce HTML, that it covers most all formatting needs something like the 
kernel documentation directory needs, integrates unchanged, directly and 
nicely into the effort Rob Landley is doing with collecting documentation 
online and is a format you can read with a program most users have open and 
available 100% of the time rather than requiring a complete stack of 
semi-obscure external software -- and I just don't see why anyone would want 
to argue that DocBook and its associated crapola should _not_ be buried in 
that same dark, desolate place where other abortive attempts at improvement 
such as GNU info already reside.

Rene.

Re: Documentation files in html format?

[Sam Ravnborg]

On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
> Hans-Jürgen Koch <hjk@linutronix.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

Re: Documentation files in html format?

[Stefan Richter]

Sam Ravnborg wrote:
> On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
>> 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.

It's true that asciidoc sources are nice to read in a plaintext viewer,
while HTML is not.  However, regardless whether the documentation is
written in HTML or docbook or asciidoc, all contributors will be forced
to learn the respective format --- otherwise the documentation will
become syntactically incorrect very quickly.

So, let's recall the start of this thread.  Stephen Hemminger wrote:
| Since the network device documentation needs a rewrite, I was thinking
| of using [CENSORED] format instead of just plain text.

What primary requirements does the network device documentation have to
fulfill?

What primary requirements does in-tree Linux kernel documentation have
to fulfill in general?

(Note that git's documentation has as one of its first and foremost
requirements that man pages can be generated.  This requirement does not
exist for the bulk of Linux kernel documentation.)

I've got a hunch that the most suitable format for Linux kernel
documentation, after careful consideration of what we want from it and
how we author and maintain it, will turn out to be...


...plaintext.
-- 
Stefan Richter
-=====-=-=== =--- -=-=-
http://arcgraph.de/sr/

Re: Documentation files in html format?

[Sam Ravnborg]

> 
> What primary requirements does in-tree Linux kernel documentation have
> to fulfill in general?

Skipping the obvious ones such as correct, up-to-date etc.
o Readable as-is
o Grepable
o buildable as structured documents or almost like a single book
o Easy to replicate structure
o Maintainable in any decent text-editor (emacs, vim, whatever)

> I've got a hunch that the most suitable format for Linux kernel
> documentation, after careful consideration of what we want from it and
> how we author and maintain it, will turn out to be...
> 
> ...plaintext.
Asciidoc is quite close to plaintext and it looks to me that the
formatting possibilities are quite good.

I spend an hour experimenting a little with
Documentation/kbuild/makefiles.txt.

Diff below shows quite a lot of changes but for the most
this is removal of the indent tab.
Most likely I could have tweaked asciidoc to accept this
but wanted to use default config.

The resulting html page can be seen here:
http://www.ravnborg.org/kbuild/makefiles.html

Produced using:
asciidoc -a toc -a numbered makefiles.txt

I would say that the asciidoc formatted plaintext text
are readable despite the simple markup.
And someone coming later will have no problems to follow
the original markup.

Btw. is is not a full conversion, I stopped after a few chapters.
asciidoc should be able to produce the index automatically
but I had no luck but then I did not try hard either.

	Sam


 makefiles.txt |  397 ++++++++++++++++++++++++++--------------------------------
 1 file changed, 180 insertions(+), 217 deletions(-)

diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index e08ef87..04f4d43 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -1,59 +1,18 @@
 Linux Kernel Makefiles
+======================
 
 This document describes the Linux kernel Makefiles.
 
-=== Table of Contents
-
-	=== 1 Overview
-	=== 2 Who does what
-	=== 3 The kbuild files
-	   --- 3.1 Goal definitions
-	   --- 3.2 Built-in object goals - obj-y
-	   --- 3.3 Loadable module goals - obj-m
-	   --- 3.4 Objects which export symbols
-	   --- 3.5 Library file goals - lib-y
-	   --- 3.6 Descending down in directories
-	   --- 3.7 Compilation flags
-	   --- 3.8 Command line dependency
-	   --- 3.9 Dependency tracking
-	   --- 3.10 Special Rules
-	   --- 3.11 $(CC) support functions
-
-	=== 4 Host Program support
-	   --- 4.1 Simple Host Program
-	   --- 4.2 Composite Host Programs
-	   --- 4.3 Defining shared libraries
-	   --- 4.4 Using C++ for host programs
-	   --- 4.5 Controlling compiler options for host programs
-	   --- 4.6 When host programs are actually built
-	   --- 4.7 Using hostprogs-$(CONFIG_FOO)
-
-	=== 5 Kbuild clean infrastructure
-
-	=== 6 Architecture Makefiles
-	   --- 6.1 Set variables to tweak the build to the architecture
-	   --- 6.2 Add prerequisites to archprepare:
-	   --- 6.3 List directories to visit when descending
-	   --- 6.4 Architecture-specific boot images
-	   --- 6.5 Building non-kbuild targets
-	   --- 6.6 Commands useful for building a boot image
-	   --- 6.7 Custom kbuild commands
-	   --- 6.8 Preprocessing linker scripts
-
-	=== 7 Kbuild Variables
-	=== 8 Makefile language
-	=== 9 Credits
-	=== 10 TODO
-
-=== 1 Overview
+== Overview
 
 The Makefiles have five parts:
-
-	Makefile		the top Makefile.
-	.config			the kernel configuration file.
-	arch/$(ARCH)/Makefile	the arch Makefile.
-	scripts/Makefile.*	common rules etc. for all kbuild Makefiles.
-	kbuild Makefiles	there are about 500 of these.
+`-----------------------`-------------------------------------------
+Makefile		the top Makefile.
+.config			the kernel configuration file.
+arch/$(ARCH)/Makefile	the arch Makefile.
+scripts/Makefile.*	common rules etc. for all kbuild Makefiles.
+kbuild Makefiles	there are about 500 of these.
+--------------------------------------------------------------------
 
 The top Makefile reads the .config file, which comes from the kernel
 configuration process.
@@ -76,32 +35,36 @@ scripts/Makefile.* contains all the definitions/rules etc. that
 are used to build the kernel based on the kbuild makefiles.
 
 
-=== 2 Who does what
+== Who does what
 
 People have four different relationships with the kernel Makefiles.
 
-*Users* are people who build kernels.  These people type commands such as
+*Users*:-
+are people who build kernels.  These people type commands such as
 "make menuconfig" or "make".  They usually do not read or edit
 any kernel Makefiles (or any other source files).
 
-*Normal developers* are people who work on features such as device
+*Normal developers*:-
+are people who work on features such as device
 drivers, file systems, and network protocols.  These people need to
 maintain the kbuild Makefiles for the subsystem they are
 working on.  In order to do this effectively, they need some overall
 knowledge about the kernel Makefiles, plus detailed knowledge about the
 public interface for kbuild.
 
-*Arch developers* are people who work on an entire architecture, such
+*Arch developers*:-
+are people who work on an entire architecture, such
 as sparc or ia64.  Arch developers need to know about the arch Makefile
 as well as kbuild Makefiles.
 
-*Kbuild developers* are people who work on the kernel build system itself.
+*Kbuild developers*:-
+are people who work on the kernel build system itself.
 These people need to know about all aspects of the kernel Makefiles.
 
 This document is aimed towards normal developers and arch developers.
 
 
-=== 3 The kbuild files
+== The kbuild files
 
 Most Makefiles within the kernel are kbuild Makefiles that use the
 kbuild infrastructure. This chapter introduces the syntax used in the
@@ -113,141 +76,141 @@ file will be used.
 Section 3.1 "Goal definitions" is a quick intro, further chapters provide
 more details, with real examples.
 
---- 3.1 Goal definitions
-
-	Goal definitions are the main part (heart) of the kbuild Makefile.
-	These lines define the files to be built, any special compilation
-	options, and any subdirectories to be entered recursively.
-
-	The most simple kbuild makefile contains one line:
-
-	Example:
-		obj-y += foo.o
-
-	This tells kbuild that there is one object in that directory, named
-	foo.o. foo.o will be built from foo.c or foo.S.
-
-	If foo.o shall be built as a module, the variable obj-m is used.
-	Therefore the following pattern is often used:
-
-	Example:
-		obj-$(CONFIG_FOO) += foo.o
-
-	$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
-	If CONFIG_FOO is neither y nor m, then the file will not be compiled
-	nor linked.
-
---- 3.2 Built-in object goals - obj-y
-
-	The kbuild Makefile specifies object files for vmlinux
-	in the $(obj-y) lists.  These lists depend on the kernel
-	configuration.
-
-	Kbuild compiles all the $(obj-y) files.  It then calls
-	"$(LD) -r" to merge these files into one built-in.o file.
-	built-in.o is later linked into vmlinux by the parent Makefile.
-
-	The order of files in $(obj-y) is significant.  Duplicates in
-	the lists are allowed: the first instance will be linked into
-	built-in.o and succeeding instances will be ignored.
-
-	Link order is significant, because certain functions
-	(module_init() / __initcall) will be called during boot in the
-	order they appear. So keep in mind that changing the link
-	order may e.g. change the order in which your SCSI
-	controllers are detected, and thus your disks are renumbered.
-
-	Example:
-		#drivers/isdn/i4l/Makefile
-		# Makefile for the kernel ISDN subsystem and device drivers.
-		# Each configuration option enables a list of files.
-		obj-$(CONFIG_ISDN)             += isdn.o
-		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
-
---- 3.3 Loadable module goals - obj-m
-
-	$(obj-m) specify object files which are built as loadable
-	kernel modules.
-
-	A module may be built from one source file or several source
-	files. In the case of one source file, the kbuild makefile
-	simply adds the file to $(obj-m).
-
-	Example:
-		#drivers/isdn/i4l/Makefile
-		obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
-
-	Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'
-
-	If a kernel module is built from several source files, you specify
-	that you want to build a module in the same way as above.
-
-	Kbuild needs to know which the parts that you want to build your
-	module from, so you have to tell it by setting an
-	$(<module_name>-objs) variable.
-
-	Example:
-		#drivers/isdn/i4l/Makefile
-		obj-$(CONFIG_ISDN) += isdn.o
-		isdn-objs := isdn_net_lib.o isdn_v110.o isdn_common.o
-
-	In this example, the module name will be isdn.o. Kbuild will
-	compile the objects listed in $(isdn-objs) and then run
-	"$(LD) -r" on the list of these files to generate isdn.o.
-
-	Kbuild recognises objects used for composite objects by the suffix
-	-objs, and the suffix -y. This allows the Makefiles to use
-	the value of a CONFIG_ symbol to determine if an object is part
-	of a composite object.
-
-	Example:
-		#fs/ext2/Makefile
-	        obj-$(CONFIG_EXT2_FS)        += ext2.o
-		ext2-y                       := balloc.o bitmap.o
-	        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
-
-	In this example, xattr.o is only part of the composite object
-	ext2.o if $(CONFIG_EXT2_FS_XATTR) evaluates to 'y'.
-
-	Note: Of course, when you are building objects into the kernel,
-	the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
-	kbuild will build an ext2.o file for you out of the individual
-	parts and then link this into built-in.o, as you would expect.
-
---- 3.4 Objects which export symbols
-
-	No special notation is required in the makefiles for
-	modules exporting symbols.
-
---- 3.5 Library file goals - lib-y
-
-	Objects listed with obj-* are used for modules, or
-	combined in a built-in.o for that specific directory.
-	There is also the possibility to list objects that will
-	be included in a library, lib.a.
-	All objects listed with lib-y are combined in a single
-	library for that directory.
-	Objects that are listed in obj-y and additionally listed in
-	lib-y will not be included in the library, since they will
-	be accessible anyway.
-	For consistency, objects listed in lib-m will be included in lib.a.
-
-	Note that the same kbuild makefile may list files to be built-in
-	and to be part of a library. Therefore the same directory
-	may contain both a built-in.o and a lib.a file.
-
-	Example:
-		#arch/i386/lib/Makefile
-		lib-y    := checksum.o delay.o
-
-	This will create a library lib.a based on checksum.o and delay.o.
-	For kbuild to actually recognize that there is a lib.a being built,
-	the directory shall be listed in libs-y.
-	See also "6.3 List directories to visit when descending".
-
-	Use of lib-y is normally restricted to lib/ and arch/*/lib.
-
---- 3.6 Descending down in directories
+=== Goal definitions
+
+Goal definitions are the main part (heart) of the kbuild Makefile.
+These lines define the files to be built, any special compilation
+options, and any subdirectories to be entered recursively.
+
+The most simple kbuild makefile contains one line:
+
+----
+	obj-y += foo.o
+----
+This tells kbuild that there is one object in that directory, named
+foo.o. foo.o will be built from foo.c or foo.S.
+
+If foo.o shall be built as a module, the variable `obj-m` is used.
+Therefore the following pattern is often used:
+
+----
+	obj-$(CONFIG_FOO) += foo.o
+----
+`$(CONFIG_FOO)` evaluates to either y (for built-in) or m (for module).
+If `CONFIG_FOO` is neither y nor m, then the file will not be compiled
+nor linked.
+
+=== Built-in object goals - obj-y
+
+The kbuild Makefile specifies object files for vmlinux
+in the `obj-y` lists.  These lists depend on the kernel
+configuration.
+
+Kbuild compiles all the +obj-y+ files.  It then calls
+`$(LD) -r` to merge these files into one built-in.o file.
+built-in.o is later linked into vmlinux by the parent Makefile.
+
+The order of files in `obj-y` is significant.  Duplicates in
+the lists are allowed: the first instance will be linked into
+built-in.o and succeeding instances will be ignored.
+
+Link order is significant, because certain functions
+(module_init() / __initcall) will be called during boot in the
+order they appear. So keep in mind that changing the link
+order may e.g. change the order in which your SCSI
+controllers are detected, and thus your disks are renumbered.
+
+----
+	#drivers/isdn/i4l/Makefile
+	# Makefile for the kernel ISDN subsystem and device drivers.
+	# Each configuration option enables a list of files.
+	obj-$(CONFIG_ISDN)             += isdn.o
+	obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+----
+=== Loadable module goals - obj-m
+
+`obj-m` specify object files which are built as loadable
+kernel modules.
+
+A module may be built from one source file or several source
+files. In the case of one source file, the kbuild makefile
+simply adds the file to `obj-m`.
+
+----
+	#drivers/isdn/i4l/Makefile
+	obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+----
+Note: In this example `$(CONFIG_ISDN_PPP_BSDCOMP)` evaluates to 'm'
+
+If a kernel module is built from several source files, you specify
+that you want to build a module in the same way as above.
+
+Kbuild needs to know which the parts that you want to build your
+module from, so you have to tell it by setting an
+`<module_name>-objs` variable.
+
+----
+	#drivers/isdn/i4l/Makefile
+	obj-$(CONFIG_ISDN) += isdn.o
+	isdn-objs := isdn_net_lib.o isdn_v110.o isdn_common.o
+----
+In this example, the module name will be isdn.o. Kbuild will
+compile the objects listed in +isdn-objs+ and then run
+`$(LD) -r` on the list of these files to generate isdn.o.
+
+Kbuild recognises objects used for composite objects by the suffix
+`-objs`, and the suffix `-y`. This allows the Makefiles to use
+the value of a `CONFIG_` symbol to determine if an object is part
+of a composite object.
+
+----
+	#fs/ext2/Makefile
+        obj-$(CONFIG_EXT2_FS)        += ext2.o
+	ext2-y                       := balloc.o bitmap.o
+        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
+----
+In this example, xattr.o is only part of the composite object
+ext2.o if `$(CONFIG_EXT2_FS_XATTR)` evaluates to 'y'.
+
+Note: Of course, when you are building objects into the kernel,
+the syntax above will also work. So, if you have `CONFIG_EXT2_FS=y`,
+kbuild will build an ext2.o file for you out of the individual
+parts and then link this into built-in.o, as you would expect.
+
+=== Objects which export symbols
+
+No special notation is required in the makefiles for
+modules exporting symbols.
+
+=== Library file goals - lib-y
+
+Objects listed with `obj-*` are used for modules, or
+combined in a built-in.o for that specific directory.
+There is also the possibility to list objects that will
+be included in a library, lib.a.
+All objects listed with `lib-y` are combined in a single
+library for that directory.
+Objects that are listed in obj-y and additionally listed in
+`lib-y` will not be included in the library, since they will
+be accessible anyway.
+For consistency, objects listed in `lib-m` will be included in lib.a.
+
+Note that the same kbuild makefile may list files to be built-in
+and to be part of a library. Therefore the same directory
+may contain both a built-in.o and a lib.a file.
+
+-----
+	#arch/i386/lib/Makefile
+	lib-y    := checksum.o delay.o
+----
+This will create a library lib.a based on checksum.o and delay.o.
+For kbuild to actually recognize that there is a lib.a being built,
+the directory shall be listed in `libs-y`.
+See also "6.3 List directories to visit when descending".
+
+Use of `lib-y` is normally restricted to lib/ and arch/*/lib.
+
+=== Descending down in directories
 
 	A Makefile is only responsible for building objects in its own
 	directory. Files in subdirectories should be taken care of by
@@ -274,7 +237,7 @@ more details, with real examples.
 	names. This allows kbuild to totally skip the directory if the
 	corresponding CONFIG_ option is neither 'y' nor 'm'.
 
---- 3.7 Compilation flags
+=== Compilation flags
 
     EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS, EXTRA_ARFLAGS
 
@@ -338,7 +301,7 @@ more details, with real examples.
 		AFLAGS_head-armv.o := -DTEXTADDR=$(TEXTADDR) -traditional
 		AFLAGS_head-armo.o := -DTEXTADDR=$(TEXTADDR) -traditional
 
---- 3.9 Dependency tracking
+=== Dependency tracking
 
 	Kbuild tracks dependencies on the following:
 	1) All prerequisite files (both *.c and *.h)
@@ -348,7 +311,7 @@ more details, with real examples.
 	Thus, if you change an option to $(CC) all affected files will
 	be re-compiled.
 
---- 3.10 Special Rules
+=== Special Rules
 
 	Special rules are used when the kbuild infrastructure does
 	not provide the required support. A typical example is
@@ -385,7 +348,7 @@ more details, with real examples.
 	to prerequisites are referenced with $(src) (because they are not
 	generated files).
 
---- 3.11 $(CC) support functions
+=== $(CC) support functions
 
 	The kernel may be built with several different versions of
 	$(CC), each supporting a unique set of features and options.
@@ -516,7 +479,7 @@ more details, with real examples.
 	In this example for a specific GCC version the build will error out explaining
 	to the user why it stops.
 
-=== 4 Host Program support
+== Host Program support
 
 Kbuild supports building executables on the host for use during the
 compilation stage.
@@ -530,7 +493,7 @@ This can be done in two ways. Either add the dependency in a rule,
 or utilise the variable $(always).
 Both possibilities are described in the following.
 
---- 4.1 Simple Host Program
+=== Simple Host Program
 
 	In some cases there is a need to compile and run a program on the
 	computer where the build is running.
@@ -544,7 +507,7 @@ Both possibilities are described in the following.
 	c-source file named bin2hex.c located in the same directory as
 	the Makefile.
 
---- 4.2 Composite Host Programs
+=== Composite Host Programs
 
 	Host programs can be made up based on composite objects.
 	The syntax used to define composite objects for host programs is
@@ -563,7 +526,7 @@ Both possibilities are described in the following.
 	Finally, the two .o files are linked to the executable, lxdialog.
 	Note: The syntax <executable>-y is not permitted for host-programs.
 
---- 4.3 Defining shared libraries
+=== Defining shared libraries
 
 	Objects with extension .so are considered shared libraries, and
 	will be compiled as position independent objects.
@@ -585,7 +548,7 @@ Both possibilities are described in the following.
 	linked as a shared library libkconfig.so. C++ is not supported for
 	shared libraries.
 
---- 4.4 Using C++ for host programs
+=== Using C++ for host programs
 
 	kbuild offers support for host programs written in C++. This was
 	introduced solely to support kconfig, and is not recommended
@@ -608,7 +571,7 @@ Both possibilities are described in the following.
 		qconf-cxxobjs := qconf.o
 		qconf-objs    := check.o
 
---- 4.5 Controlling compiler options for host programs
+=== Controlling compiler options for host programs
 
 	When compiling host programs, it is possible to set specific flags.
 	The programs will always be compiled utilising $(HOSTCC) passed
@@ -636,7 +599,7 @@ Both possibilities are described in the following.
 	When linking qconf, it will be passed the extra option
 	"-L$(QTDIR)/lib".
 
---- 4.6 When host programs are actually built
+=== When host programs are actually built
 
 	Kbuild will only build host-programs when they are referenced
 	as a prerequisite.
@@ -667,7 +630,7 @@ Both possibilities are described in the following.
 	This will tell kbuild to build lxdialog even if not referenced in
 	any rule.
 
---- 4.7 Using hostprogs-$(CONFIG_FOO)
+=== Using hostprogs-$(CONFIG_FOO)
 
 	A typical pattern in a Kbuild file looks like this:
 
@@ -681,7 +644,7 @@ Both possibilities are described in the following.
 	like hostprogs-y. But only hostprogs-y is recommended to be used
 	when no CONFIG symbols are involved.
 
-=== 5 Kbuild clean infrastructure
+== Kbuild clean infrastructure
 
 "make clean" deletes most generated files in the obj tree where the kernel
 is compiled. This includes generated files such as host programs.
@@ -741,7 +704,7 @@ is not operational at that point.
 Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
 be visited during "make clean".
 
-=== 6 Architecture Makefiles
+== Architecture Makefiles
 
 The top level Makefile sets up the environment and does the preparation,
 before starting to descend down in the individual directories.
@@ -770,7 +733,7 @@ When kbuild executes, the following steps are followed (roughly):
    - Preparing initrd images and the like
 
 
---- 6.1 Set variables to tweak the build to the architecture
+=== Set variables to tweak the build to the architecture
 
     LDFLAGS		Generic $(LD) options
 
@@ -866,7 +829,7 @@ When kbuild executes, the following steps are followed (roughly):
 	for loadable kernel modules.
 
 
---- 6.2 Add prerequisites to archprepare:
+=== Add prerequisites to archprepare:
 
 	The archprepare: rule is used to list prerequisites that need to be
 	built before starting to descend down in the subdirectories.
@@ -882,7 +845,7 @@ When kbuild executes, the following steps are followed (roughly):
 	generating offset header files.
 
 
---- 6.3 List directories to visit when descending
+=== List directories to visit when descending
 
 	An arch Makefile cooperates with the top Makefile to define variables
 	which specify how to build the vmlinux file.  Note that there is no
@@ -911,7 +874,7 @@ When kbuild executes, the following steps are followed (roughly):
 		drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/
 
 
---- 6.4 Architecture-specific boot images
+=== Architecture-specific boot images
 
 	An arch Makefile specifies goals that take the vmlinux file, compress
 	it, wrap it in bootstrapping code, and copy the resulting files
@@ -962,7 +925,7 @@ When kbuild executes, the following steps are followed (roughly):
 
 	When "make" is executed without arguments, bzImage will be built.
 
---- 6.5 Building non-kbuild targets
+=== Building non-kbuild targets
 
     extra-y
 
@@ -982,7 +945,7 @@ When kbuild executes, the following steps are followed (roughly):
 	shall be built, but shall not be linked as part of built-in.o.
 
 
---- 6.6 Commands useful for building a boot image
+=== Commands useful for building a boot image
 
 	Kbuild provides a few macros that are useful when building a
 	boot image.
@@ -1048,7 +1011,7 @@ When kbuild executes, the following steps are followed (roughly):
 	      obvious reason.
 
 
---- 6.7 Custom kbuild commands
+=== Custom kbuild commands
 
 	When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
 	of a command is normally displayed.
@@ -1075,7 +1038,7 @@ When kbuild executes, the following steps are followed (roughly):
 	will be displayed with "make KBUILD_VERBOSE=0".
 
 
---- 6.8 Preprocessing linker scripts
+=== Preprocessing linker scripts
 
 	When the vmlinux image is built, the linker script
 	arch/$(ARCH)/kernel/vmlinux.lds is used.
@@ -1106,7 +1069,7 @@ When kbuild executes, the following steps are followed (roughly):
 	architecture-specific files.
 
 
-=== 7 Kbuild Variables
+== Kbuild Variables
 
 The top Makefile exports the following variables:
 
@@ -1168,7 +1131,7 @@ The top Makefile exports the following variables:
 	INSTALL_MOD_STRIP will used as the option(s) to the strip command.
 
 
-=== 8 Makefile language
+== Makefile language
 
 The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
 use only the documented features of GNU Make, but they do use many
@@ -1187,14 +1150,14 @@ time the left-hand side is used.
 There are some cases where "=" is appropriate.  Usually, though, ":="
 is the right choice.
 
-=== 9 Credits
+== Credits
 
 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 Updates by Sam Ravnborg <sam@ravnborg.org>
 Language QA by Jan Engelhardt <jengelh@gmx.de>
 
-=== 10 TODO
+== TODO
 
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.

Re: Documentation files in html format?

[Rene Herman]

On 08/10/2007 10:12 PM, Sam Ravnborg wrote:

>> What primary requirements does in-tree Linux kernel documentation have
>> to fulfill in general?
> 
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or almost like a single book
> o Easy to replicate structure
> o Maintainable in any decent text-editor (emacs, vim, whatever)

Easy to put online?

> Asciidoc is quite close to plaintext and it looks to me that the
> formatting possibilities are quite good.
> 
> I spend an hour experimenting a little with
> Documentation/kbuild/makefiles.txt.
> 
> Diff below shows quite a lot of changes but for the most
> this is removal of the indent tab.
> Most likely I could have tweaked asciidoc to accept this
> but wanted to use default config.
> 
> The resulting html page can be seen here:
> http://www.ravnborg.org/kbuild/makefiles.html

FWIW, this looks very good to me...

Rene.

Re: Documentation files in html format?

[Stefan Richter]

Rene Herman wrote:
> On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
> 
>>> What primary requirements does in-tree Linux kernel documentation have
>>> to fulfill in general?
>>
>> Skipping the obvious ones such as correct, up-to-date etc.
>> o Readable as-is
>> o Grepable
>> o buildable as structured documents or almost like a single book
>> o Easy to replicate structure
>> o Maintainable in any decent text-editor (emacs, vim, whatever)

Low entry barrier for patches from unsuspecting occasional contributors?

> Easy to put online?

http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=Documentation
http://lxr.linux.no/source/Documentation/
http://users.sosdg.org/~qiyong/lxr/source/Documentation/
http://www.linux-m32r.org/lxr/http/source/Documentation/
http://lxr.free-electrons.com/source/Documentation/


(I admit though that formats like asciidoc or docbook are beneficial for
larger documentation files which want chapters, table of contents, and
internal crossreferences.)
-- 
Stefan Richter
-=====-=-=== =--- -=-==
http://arcgraph.de/sr/

Re: Documentation files in html format?

[Rene Herman]

On 08/11/2007 08:31 AM, Stefan Richter wrote:

> Rene Herman wrote:
>> On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
>>
>>>> What primary requirements does in-tree Linux kernel documentation have
>>>> to fulfill in general?
>>> Skipping the obvious ones such as correct, up-to-date etc.
>>> o Readable as-is
>>> o Grepable
>>> o buildable as structured documents or almost like a single book
>>> o Easy to replicate structure
>>> o Maintainable in any decent text-editor (emacs, vim, whatever)
> 
> Low entry barrier for patches from unsuspecting occasional contributors?

Indeed, and AsciiDoc seems to fit nicely; it's easy to work from example. 
Look at:

http://www.methods.co.nz/asciidoc/asciidoc.txt

which is the source for:

http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html

In fact, one of the more important things for lowering the entry barrier is 
providing contributors with infrastructure so that a contributor is free to 
concentrate more on the what than the how and as was already argued in this 
thread, when you start laying down structure and rules for Documentation/, 
you end up with something close to AsciiDoc anyway.

>> Easy to put online?
> 
> http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=Documentation
> http://lxr.linux.no/source/Documentation/
> http://users.sosdg.org/~qiyong/lxr/source/Documentation/
> http://www.linux-m32r.org/lxr/http/source/Documentation/
> http://lxr.free-electrons.com/source/Documentation/

Easy to put online in a nice way. Compare:

http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kbuild/makefiles.txt;h=e08ef8759a0780caaa237a5a88ad8d921208af98;hb=HEAD

and

http://www.ravnborg.org/kbuild/makefiles.html

as Sam posted. I certainly think the latter reads nicer (it's missing the 
table of content for now, but that appears to be a tool option).

> (I admit though that formats like asciidoc or docbook are beneficial for
> larger documentation files which want chapters, table of contents, and
> internal crossreferences.)

I personally wouldn't want to rudely outlaw plain text -- the discussion 
happened due to someone suggesting redoing some documentation in HTML. Some 
people suggested DocBook (hnnng!) and now asciidoc.

I think that DocBook is a bloody trainwreck (yes, "make pdfdocs" bombs out 
for me at the moment as well -- has it ever been different) but that some 
simple formatting quite often makes for an improvement over plain text.

HTML directly would do as far as I'm concerned, but AsciiDoc can also 
generate that and additionally imposes more structure (in the sense of 
uniformity) than direct HTML would. On the downside it still requires some 
external software, on the upside it directly translates to many more formats 
when viewed as a DocBook pre-processor.

Works for me...

Rene.

Re: Documentation files in html format?

[Jan Engelhardt]

On Aug 10 2007 22:12, Sam Ravnborg wrote:
>Asciidoc is quite close to plaintext and it looks to me that the
>formatting possibilities are quite good.

How about mediwiki text?

'''Users'''
:are people who build kernels.

'''Normal developers'''
:are this and that....


>+=== Goal definitions
>+
>+Goal definitions are the main part (heart) of the kbuild Makefile.
>+These lines define the files to be built, any special compilation
>+options, and any subdirectories to be entered recursively.
>+
>+The most simple kbuild makefile contains one line:
>+
>+----
>+	obj-y += foo.o
>+----
>+This tells kbuild that there is one object in that directory, named
>+foo.o. foo.o will be built from foo.c or foo.S.

(wikitext continued)
The most simple kbuild makefile contains one line:

 obj-y += foo.o

This tells kbuild that...



	Jan
-- 

Re: Documentation files in html format?

[Randy Dunlap]

On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:

> > 
> > What primary requirements does in-tree Linux kernel documentation have
> > to fulfill in general?
> 
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or almost like a single book
> o Easy to replicate structure
> o Maintainable in any decent text-editor (emacs, vim, whatever)
> 
> > I've got a hunch that the most suitable format for Linux kernel
> > documentation, after careful consideration of what we want from it and
> > how we author and maintain it, will turn out to be...
> > 
> > ...plaintext.
> Asciidoc is quite close to plaintext and it looks to me that the
> formatting possibilities are quite good.
> 
> I spend an hour experimenting a little with
> Documentation/kbuild/makefiles.txt.

Hi Sam,

Sorry for the late question (I've been away :).

Was your makefiles.txt conversion done totally by hand?
Could it be automated?

or maybe there is not enough volume to even worry about that.

Yes, evaluating asciidoc has been on my radar (todo list) for
some time now.


> Diff below shows quite a lot of changes but for the most
> this is removal of the indent tab.
> Most likely I could have tweaked asciidoc to accept this
> but wanted to use default config.
> 
> The resulting html page can be seen here:
> http://www.ravnborg.org/kbuild/makefiles.html
> 
> Produced using:
> asciidoc -a toc -a numbered makefiles.txt
> 
> I would say that the asciidoc formatted plaintext text
> are readable despite the simple markup.
> And someone coming later will have no problems to follow
> the original markup.
> 
> Btw. is is not a full conversion, I stopped after a few chapters.
> asciidoc should be able to produce the index automatically
> but I had no luck but then I did not try hard either.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Randy Dunlap]

On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:

> > 
> > What primary requirements does in-tree Linux kernel documentation have
> > to fulfill in general?
> 
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or almost like a single book
> o Easy to replicate structure
> o Maintainable in any decent text-editor (emacs, vim, whatever)
> 
> > I've got a hunch that the most suitable format for Linux kernel
> > documentation, after careful consideration of what we want from it and
> > how we author and maintain it, will turn out to be...
> > 
> > ...plaintext.
> Asciidoc is quite close to plaintext and it looks to me that the
> formatting possibilities are quite good.
> 
> I spend an hour experimenting a little with
> Documentation/kbuild/makefiles.txt.

[resend, sorry about duplicates]

Hi Sam,

Sorry for the late question (I've been away :).

Was your makefiles.txt conversion done totally by hand?
Could it be automated?

or maybe there is not enough volume to even worry about that.

Yes, evaluating asciidoc has been on my radar (todo list) for
some time now.


> Diff below shows quite a lot of changes but for the most
> this is removal of the indent tab.
> Most likely I could have tweaked asciidoc to accept this
> but wanted to use default config.
> 
> The resulting html page can be seen here:
> http://www.ravnborg.org/kbuild/makefiles.html
> 
> Produced using:
> asciidoc -a toc -a numbered makefiles.txt
> 
> I would say that the asciidoc formatted plaintext text
> are readable despite the simple markup.
> And someone coming later will have no problems to follow
> the original markup.
> 
> Btw. is is not a full conversion, I stopped after a few chapters.
> asciidoc should be able to produce the index automatically
> but I had no luck but then I did not try hard either.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Sam Ravnborg]

> Hi Sam,
> 
> Sorry for the late question (I've been away :).
> 
> Was your makefiles.txt conversion done totally by hand?
Yes. A few search&replace, the rest manual.

> Could it be automated?
For text with a unifom structure like makefiles.txt - yes.

	Sam

Re: Documentation files in html format?

[Oleg Verych]

* Date: Fri, 10 Aug 2007 09:40:47 +0200
* Sam Ravnborg:
>
> 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.

just plain text

another option: txt2tags && sed

For me anything else, like man, info, (xml, html)+css, is a brain
damage. If it's fine for you -- it's your wasted time and mood.

(yet another big useless thread on useless OT, how sad).
____

Re: Documentation files in html format?

[Bob Copeland]

On 8/9/07, Stephen Hemminger <shemminger@linux-foundation.org> 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.

Why not just use asciidoc?  Slightly worse than plain text, slightly
better than angle brackets everywhere.  Nothing is more annoying than
having to use lynx to read documentation because someone went tags
crazy.

-Bob

Re: Documentation files in html format?

[Stefan Richter]

Stephen Hemminger wrote:
> Advantages of html:
>   * basic formatting like lists, italics, etc

Plaintext has lists too.  See for example
<20070809113122.3aa508e4@oldman.hamilton.local>.  ;-)

It's also possible to approximate bold face, italics, and underlines in
plaintext.

>   * easier to integrate into other places and retain formatting

Out-of-tree places?

>   * ability to link documents and to external sources easier

In which way are URIs and other references in HTML easier than in plaintext?

> Downsides:
>   * can become too formatted and unclear
>   * accessibility and translation issues?
>   * even more style issues

Indeed.
-- 
Stefan Richter
-=====-=-=== =--- -=--=
http://arcgraph.de/sr/

Re: Documentation files in html format?

[Brennan Ashton]

On 8/9/07, Stefan Richter <stefanr@s5r6.in-berlin.de> wrote:
> Stephen Hemminger wrote:
> > Advantages of html:
> >   * basic formatting like lists, italics, etc
>
> Plaintext has lists too.  See for example
> <20070809113122.3aa508e4@oldman.hamilton.local>.  ;-)
>
> It's also possible to approximate bold face, italics, and underlines in
> plaintext.
>
> >   * easier to integrate into other places and retain formatting
>
> Out-of-tree places?
>
> >   * ability to link documents and to external sources easier
>
> In which way are URIs and other references in HTML easier than in plaintext?
>
> > Downsides:
> >   * can become too formatted and unclear
> >   * accessibility and translation issues?
> >   * even more style issues
>
> Indeed.
> --
> Stefan Richter
> -=====-=-=== =--- -=--=
> http://arcgraph.de/sr/
> -
> 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/
>
I am with you on this one, i am less than convinced that HTML is
better, IMHO it is a wrong direction.  Plain Text documentation is one
of the things i love about linux, it has worked for so many years why
change now. As Stefan explained there are simple ways to get around
all of the points that you gave.

-- 
Brennan Ashton

Re: Documentation files in html format?

[Jesper Juhl]

On 09/08/07, Stephen Hemminger <shemminger@linux-foundation.org> 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

 - List item 1
 - List item 2
 - List item 3

/italic text/
*bold text*
_underlined text_


>   * easier to integrate into other places and retain formatting

Hmm, I'm not sure I agree, generally plain tet integrates easily into
everything, html not so. As for formatting, you usually always have to
tweak that by hand anyway, might as well leave it as plain text..

>   * ability to link documents and to external sources easier

How is <a href="http://kernel.org/">kernel.org</a> easier to handle
than plain http://kernel.org/ ?

>
> Downsides:
>   * can become too formatted and unclear

Yup.

>   * accessibility and translation issues?

Those exist whatever format you pick.

>   * even more style issues

Indeed.


I for one vote for just keeping things as plain text, it's so much
easier work with - grep, sed, awk etc...


-- 
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

Re: Documentation files in html format?

[Jan Engelhardt]

On Aug 9 2007 22:03, Jesper Juhl wrote:
>On 09/08/07, Stephen Hemminger <shemminger@linux-foundation.org> 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
>
> - List item 1
> - List item 2
> - List item 3
>
>/italic text/
>*bold text*
>_underlined text_

This is likely to generate false positives.


	Jan
-- 

Re: Documentation files in html format?

[Willy Tarreau]

Hi Stephen,

On Thu, Aug 09, 2007 at 11:31:22AM +0100, 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.

I've read pro-plain text arguments, so I'll not repeat them. I also see
another advantage to plain text : it's very easy to draw ascii-art
diagrams of anything. It only takes a few minutes, is always inline
and readable with any tool. Look at the bonding doc I wrote and updated
in 2000, people have updated or duplicated some of the diagrams when
they have added features. Something they would definitely not have done
if it had required some strange tool.

Also, the advantage of plain text is that it stays compatible with
everything though the years. Had I used some random tool in 2000 for
this, I'm not sure the tool would still exist right now. Look at RFCs.
Nothing fancy, just readable. Even the TCP FSM in rfc793 from 26 years
ago is readable, understandable, and updatable by anybody (though it's
a little mit messy). And it's somewhat an extreme case ;-)

I'd prefer that you define some writing conventions for plain-text
documents that anyone should try follow, starting with the 80-cols
limit to make Davem happy. I think that many of us can help define
such a "standard" indicating how to underline subtitles, how to
enumerate a list, how to avoid using tabs, how to write boxes and
arrows in their diagrams, etc...

Best regards,
Willy

Re: Documentation files in html format?

[J. Bruce Fields]

On Fri, Aug 10, 2007 at 10:17:04PM +0200, Willy Tarreau wrote:
> I've read pro-plain text arguments, so I'll not repeat them. I also see
> another advantage to plain text : it's very easy to draw ascii-art
> diagrams of anything. It only takes a few minutes, is always inline
> and readable with any tool.

Asciidoc should preserve ascii-art diagrams OK; the git docs use them
all over.

Not that I'd necessarily push asciidoc.  But:

> I'd prefer that you define some writing conventions for plain-text
> documents that anyone should try follow, starting with the 80-cols
> limit to make Davem happy. I think that many of us can help define
> such a "standard" indicating how to underline subtitles, how to
> enumerate a list, how to avoid using tabs, how to write boxes and
> arrows in their diagrams, etc...

... at the point where you actually start setting standards for subtitle
underlining and list enumeration, you'd want to take another look at
asciidoc; since it already defines conventions for that stuff (which
are probably close to what people would do anyway), it might make sense
just to start using asciidoc.

--b.

Re: Documentation files in html format?

[Willy Tarreau]

On Fri, Aug 10, 2007 at 04:40:25PM -0400, J. Bruce Fields wrote:
> On Fri, Aug 10, 2007 at 10:17:04PM +0200, Willy Tarreau wrote:
> > I've read pro-plain text arguments, so I'll not repeat them. I also see
> > another advantage to plain text : it's very easy to draw ascii-art
> > diagrams of anything. It only takes a few minutes, is always inline
> > and readable with any tool.
> 
> Asciidoc should preserve ascii-art diagrams OK; the git docs use them
> all over.
> 
> Not that I'd necessarily push asciidoc.  But:
> 
> > I'd prefer that you define some writing conventions for plain-text
> > documents that anyone should try follow, starting with the 80-cols
> > limit to make Davem happy. I think that many of us can help define
> > such a "standard" indicating how to underline subtitles, how to
> > enumerate a list, how to avoid using tabs, how to write boxes and
> > arrows in their diagrams, etc...
> 
> ... at the point where you actually start setting standards for subtitle
> underlining and list enumeration, you'd want to take another look at
> asciidoc; since it already defines conventions for that stuff (which
> are probably close to what people would do anyway), it might make sense
> just to start using asciidoc.

The problem I have with asciidoc is that it's a nightmare to get it
to work. It's what GIT uses, and after spending a whole day trying
to *build* that thing, I finally resigned and asked Junio if he could
publish the pre-formatted manpages himself, which he agreed to.

All I remember is that there was a very deep level of dependencies
through XML craps^H^H^H^H^Hpackages and I don't remember what magic
things, but one full day trying to build something to read a doc is
too much, so I imagine that I would not even have tried that long
if I had wanted to complete a doc and check that my changes looked
right.

Maybe the language is fine, but the tool needs to build first.

Willy

Re: Documentation files in html format?

[Sam Ravnborg]

> 
> The problem I have with asciidoc is that it's a nightmare to get it
> to work. It's what GIT uses, and after spending a whole day trying
> to *build* that thing, I finally resigned and asked Junio if he could
> publish the pre-formatted manpages himself, which he agreed to.

Bit uses in addition to asciidoc also docbook and a bit more.
As asciidoc is some phython scripts it should be trivial to
install with no build required.
Maybe it was the docbook stuff you had trouble with?

My Kbuild example were made without using other tools than asciidoc but
if pdf is desired some additional tools are needed.

	Sam

Re: Documentation files in html format?

[Willy Tarreau]

On Sat, Aug 11, 2007 at 01:08:30AM +0200, Sam Ravnborg wrote:
> > 
> > The problem I have with asciidoc is that it's a nightmare to get it
> > to work. It's what GIT uses, and after spending a whole day trying
> > to *build* that thing, I finally resigned and asked Junio if he could
> > publish the pre-formatted manpages himself, which he agreed to.
> 
> Bit uses in addition to asciidoc also docbook and a bit more.
> As asciidoc is some phython scripts it should be trivial to
> install with no build required.

I remember it relied on some tools to process xml, but I don't know
exactly what. It were those tools which I could not build.

> Maybe it was the docbook stuff you had trouble with?

possible, I don't remember that much, it was a painful day one year ago.

> My Kbuild example were made without using other tools than asciidoc but
> if pdf is desired some additional tools are needed.

It was just needed to build the man pages, so I would have expected it
to be pretty straight-forward too.

Willy

Re: Documentation files in html format?

[J. Bruce Fields]

On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> The problem I have with asciidoc is that it's a nightmare to get it
> to work. It's what GIT uses, and after spending a whole day trying
> to *build* that thing, I finally resigned and asked Junio if he could
> publish the pre-formatted manpages himself, which he agreed to.

I wasn't actually suggesting we use the asciidoc tools--that's a
separate question.  We could ignore them, or wait till they solve
whatever problems they may have.

I was just suggesting that if we took your suggestion of standardizing
on plain text plus some conventions for formatting lists and headers and
such, one easy way to do that might just be to adopt the asciidoc format
(or some subset thereof).  Is there any part of the asciidoc *syntax*
that you object to?

--b.

Re: Documentation files in html format?

[Willy Tarreau]

On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > The problem I have with asciidoc is that it's a nightmare to get it
> > to work. It's what GIT uses, and after spending a whole day trying
> > to *build* that thing, I finally resigned and asked Junio if he could
> > publish the pre-formatted manpages himself, which he agreed to.
> 
> I wasn't actually suggesting we use the asciidoc tools--that's a
> separate question.  We could ignore them, or wait till they solve
> whatever problems they may have.
> 
> I was just suggesting that if we took your suggestion of standardizing
> on plain text plus some conventions for formatting lists and headers and
> such, one easy way to do that might just be to adopt the asciidoc format
> (or some subset thereof).  Is there any part of the asciidoc *syntax*
> that you object to?

Not particularly. It's just slightly less readable as plain text but
OTOH produces nice documents when you have a working toolchain. But
that's a language which needs to be learned, as every such language.
Plain text on the contrary, requires no learning. The conventions are
more like suggestions to newcomers. Everyone is free to proceed as he
wants, judging by the result while writing the text.

Willy

Re: Documentation files in html format?

[Randy Dunlap]

On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:

> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> > On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > > The problem I have with asciidoc is that it's a nightmare to get it
> > > to work. It's what GIT uses, and after spending a whole day trying
> > > to *build* that thing, I finally resigned and asked Junio if he could
> > > publish the pre-formatted manpages himself, which he agreed to.
> > 
> > I wasn't actually suggesting we use the asciidoc tools--that's a
> > separate question.  We could ignore them, or wait till they solve
> > whatever problems they may have.
> > 
> > I was just suggesting that if we took your suggestion of standardizing
> > on plain text plus some conventions for formatting lists and headers and
> > such, one easy way to do that might just be to adopt the asciidoc format
> > (or some subset thereof).  Is there any part of the asciidoc *syntax*
> > that you object to?
> 
> Not particularly. It's just slightly less readable as plain text but
> OTOH produces nice documents when you have a working toolchain. But
> that's a language which needs to be learned, as every such language.
> Plain text on the contrary, requires no learning. The conventions are
> more like suggestions to newcomers. Everyone is free to proceed as he
> wants, judging by the result while writing the text.

but if we use something richer than plain text, I think that we
shouldn't need to invent yet another markup language.
Just use HTML or asciidoc or MarkDown etc...

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Randy Dunlap]

On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:

> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
> > On Fri, Aug 10, 2007 at 10:51:17PM +0200, Willy Tarreau wrote:
> > > The problem I have with asciidoc is that it's a nightmare to get it
> > > to work. It's what GIT uses, and after spending a whole day trying
> > > to *build* that thing, I finally resigned and asked Junio if he could
> > > publish the pre-formatted manpages himself, which he agreed to.
> > 
> > I wasn't actually suggesting we use the asciidoc tools--that's a
> > separate question.  We could ignore them, or wait till they solve
> > whatever problems they may have.
> > 
> > I was just suggesting that if we took your suggestion of standardizing
> > on plain text plus some conventions for formatting lists and headers and
> > such, one easy way to do that might just be to adopt the asciidoc format
> > (or some subset thereof).  Is there any part of the asciidoc *syntax*
> > that you object to?
> 
> Not particularly. It's just slightly less readable as plain text but
> OTOH produces nice documents when you have a working toolchain. But
> that's a language which needs to be learned, as every such language.
> Plain text on the contrary, requires no learning. The conventions are
> more like suggestions to newcomers. Everyone is free to proceed as he
> wants, judging by the result while writing the text.

[resend, sorry about duplicates]

but if we use something richer than plain text, I think that we
shouldn't need to invent yet another markup language.
Just use HTML or asciidoc or MarkDown etc...

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Stefan Richter]

Randy Dunlap wrote:
> On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
>> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote:
>>> I was just suggesting that if we took your suggestion of standardizing
>>> on plain text plus some conventions for formatting lists and headers and
>>> such, one easy way to do that might just be to adopt the asciidoc format
>>> (or some subset thereof).  Is there any part of the asciidoc *syntax*
>>> that you object to?
>> Not particularly. It's just slightly less readable as plain text but
>> OTOH produces nice documents when you have a working toolchain. But
>> that's a language which needs to be learned, as every such language.
>> Plain text on the contrary, requires no learning. The conventions are
>> more like suggestions to newcomers. Everyone is free to proceed as he
>> wants, judging by the result while writing the text.

> but if we use something richer than plain text, I think that we
> shouldn't need to invent yet another markup language.
> Just use HTML or asciidoc or MarkDown etc...

*If* we switch to a markup language instead of plaintext (or instead of
plaintext with style recommendations), then submitters should at least
be able to do basic syntax checks without having a toolchain installed.

E.g. provide a scripts/checkdocumentation.p[ly] similar in function to
scripts/checkpatch.pl.  (OK, that one requires a perl interpreter
installed, but that's a fair requirement.)

One note on asciidoc:  I experienced the same as Willy when I wanted to
build git with manpages on a distribution without prebuilt asciidoc.
And when I finally managed to build a minimum asciidoc setup, I was
bitten by a syntax change in the asciidoc language, requiring a small
change to git's documentation source to be compatible with both asciidoc
7.x and asciidoc 8.x IIRC.
-- 
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/

Re: Documentation files in html format?

[Sam Ravnborg]

On Sun, Aug 12, 2007 at 03:10:57PM +0200, Stefan Richter wrote:
> 
> One note on asciidoc:  I experienced the same as Willy when I wanted to
> build git with manpages on a distribution without prebuilt asciidoc.

I assume you had troubles with the docbook utilities and not asciidoc itself.
asciidoc is used to generate the format used by docbook utilities to
generate man-pages.

The html example I posted previously were made solely by asciidoc and no
additional docbook stuff.

	Sam

Re: Documentation files in html format?

[Stefan Richter]

Sam Ravnborg wrote:
> On Sun, Aug 12, 2007 at 03:10:57PM +0200, Stefan Richter wrote:
>> One note on asciidoc:  I experienced the same as Willy when I wanted to
>> build git with manpages on a distribution without prebuilt asciidoc.
> 
> I assume you had troubles with the docbook utilities and not asciidoc itself.
> asciidoc is used to generate the format used by docbook utilities to
> generate man-pages.

Probably.  I repressed the memory of that traumatizing experience.

> The html example I posted previously were made solely by asciidoc and no
> additional docbook stuff.

Good.  The vanilla asciidoc-8.2.2.tar.gz looks like it can be installed
without any prerequisites besides Python >=2.3.  (The distro which I am
currently using has prepackaged versions of asciidoc.)
-- 
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/

Re: Documentation files in html format?

[Randy Dunlap]

On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:

> Hi Stephen,
> 
> On Thu, Aug 09, 2007 at 11:31:22AM +0100, 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.
> 
> I've read pro-plain text arguments, so I'll not repeat them. I also see
> another advantage to plain text : it's very easy to draw ascii-art
> diagrams of anything. It only takes a few minutes, is always inline
> and readable with any tool. Look at the bonding doc I wrote and updated
> in 2000, people have updated or duplicated some of the diagrams when
> they have added features. Something they would definitely not have done
> if it had required some strange tool.
> 
> Also, the advantage of plain text is that it stays compatible with
> everything though the years. Had I used some random tool in 2000 for
> this, I'm not sure the tool would still exist right now. Look at RFCs.

This is getting dangerously close to an XML discussion.  ;)

ISTM (from reading the IETF mailing list) that the recommended tools
for generating plaintext RFCs are either
a) xml2rfc (from http://tools.ietf.org/inventory/author-tools)
or
b) an MS Word plugin/macro/whatever.

There is also an xml RFC to pdf/ps converter here:
http://www.arkko.com/tools/xml2pdfrfc.html


> Nothing fancy, just readable. Even the TCP FSM in rfc793 from 26 years
> ago is readable, understandable, and updatable by anybody (though it's
> a little mit messy). And it's somewhat an extreme case ;-)
> 
> I'd prefer that you define some writing conventions for plain-text
> documents that anyone should try follow, starting with the 80-cols
> limit to make Davem happy. I think that many of us can help define
> such a "standard" indicating how to underline subtitles, how to
> enumerate a list, how to avoid using tabs, how to write boxes and
> arrows in their diagrams, etc...

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Randy Dunlap]

On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:

> Hi Stephen,
> 
> On Thu, Aug 09, 2007 at 11:31:22AM +0100, 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.
> 
> I've read pro-plain text arguments, so I'll not repeat them. I also see
> another advantage to plain text : it's very easy to draw ascii-art
> diagrams of anything. It only takes a few minutes, is always inline
> and readable with any tool. Look at the bonding doc I wrote and updated
> in 2000, people have updated or duplicated some of the diagrams when
> they have added features. Something they would definitely not have done
> if it had required some strange tool.
> 
> Also, the advantage of plain text is that it stays compatible with
> everything though the years. Had I used some random tool in 2000 for
> this, I'm not sure the tool would still exist right now. Look at RFCs.

[resend, sorry about duplicates]

This is getting dangerously close to an XML discussion.  ;)

ISTM (from reading the IETF mailing list) that the recommended tools
for generating plaintext RFCs are either
a) xml2rfc (from http://tools.ietf.org/inventory/author-tools)
or
b) an MS Word plugin/macro/whatever.

There is also an xml RFC to pdf/ps converter here:
http://www.arkko.com/tools/xml2pdfrfc.html


> Nothing fancy, just readable. Even the TCP FSM in rfc793 from 26 years
> ago is readable, understandable, and updatable by anybody (though it's
> a little mit messy). And it's somewhat an extreme case ;-)
> 
> I'd prefer that you define some writing conventions for plain-text
> documents that anyone should try follow, starting with the 80-cols
> limit to make Davem happy. I think that many of us can help define
> such a "standard" indicating how to underline subtitles, how to
> enumerate a list, how to avoid using tabs, how to write boxes and
> arrows in their diagrams, etc...

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: Documentation files in html format?

[Bodo Eggert]

Jan Engelhardt <jengelh@computergmbh.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@mBlrwf80.7eggert.dyndns.org An4grd@Z.7eggert.dyndns.org

Re: Documentation files in html format?

[Jan Engelhardt]

On Aug 9 2007 14:34, Bodo Eggert wrote:
>
>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.

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

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


	Jan
-- 

Re: Documentation files in html format?

[Bodo Eggert]

On Thu, 9 Aug 2007, Jan Engelhardt wrote:
> On Aug 9 2007 14:34, Bodo Eggert wrote:

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

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