Skip to contentSkip to conversation

Documentation files in html format?

DISCUSSION Stephen Hemminger 17 participants 41 messages Aug 9, 2007 – Sep 1, 2007

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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

#1 lore raw
Quoted 6 lines · 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.

Quoted 7 lines

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.

Quoted 1 line

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

Quoted 1 line

* 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

#2 lore raw
In reply to Stephen Hemminger

Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:

Quoted 2 lines

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

#3 lore raw
Quoted 9 lines · On Thu, 9 Aug 2007 15:08:20 +0200 Hans-Jürgen Koch <[email protected]> wrote:

Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:

Quoted 2 lines

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.

#4 lore raw
In reply to Hans-Jürgen Koch
Quoted 6 lines · Hans-Jürgen Koch

Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:

Quoted 2 lines

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

#5 lore raw
Quoted 10 lines · Andi Kleen

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.

#6 lore raw
In reply to Andi Kleen
Quoted 13 lines · Andi Kleen
Quoted 5 lines · Hans-Jürgen Koch

Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:

Quoted 2 lines

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.

Quoted 6 lines

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.

#7 lore raw
In reply to Andi Kleen

Andi Kleen <[email protected]> :
[...]

Quoted 3 lines

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.

Quoted 2 lines

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.

Signature · 1 line
Ueimor
#8 lore raw
Quoted 1 line

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

#9 lore raw

Andi Kleen <[email protected]> :
[...]

Quoted 2 lines

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.

Signature · 1 line
Ueimor
#10 lore raw
Quoted 8 lines · Francois Romieu

Andi Kleen <[email protected]> :
[...]

Quoted 2 lines

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.

#11 lore raw
In reply to Andi Kleen
Quoted 14 lines · Andi Kleen
Quoted 6 lines · Hans-Jürgen Koch

Am Donnerstag 09 August 2007 12:31 schrieb Stephen Hemminger:

Quoted 2 lines

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.

Quoted 6 lines

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

#12 lore raw
Quoted 10 lines · Sam Ravnborg
Quoted 2 lines · Andi Kleen

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.

Signature · 3 lines
Stefan Richter
-=====-=-=== =--- -=-=-
http://arcgraph.de/sr/
#13 lore raw
Quoted 3 lines

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)

Quoted 5 lines

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(-)
Documentation/kbuild/makefiles.txt +180 -217
index e08ef87..04f4d43 100644
@@ -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:[email protected]>
 Updates by Kai Germaschewski <[email protected]>
 Updates by Sam Ravnborg <[email protected]>
 Language QA by Jan Engelhardt <[email protected]>
 
-=== 10 TODO
+== TODO
 
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
#14 lore raw
Quoted 9 lines · Sam Ravnborg
Quoted 2 lines

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?

Quoted 6 lines

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.

Quoted 7 lines

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.

#15 lore raw
Quoted 11 lines · Rene Herman
Quoted 9 lines · Sam Ravnborg
Quoted 2 lines

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?

Quoted 1 line

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

Signature · 3 lines
Stefan Richter
-=====-=-=== =--- -=-==
http://arcgraph.de/sr/
#16 lore raw
Quoted 5 lines · Stefan Richter
Quoted 4 lines · Rene Herman
Quoted 2 lines · Sam Ravnborg
Quoted 2 lines

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

Quoted 8 lines
Quoted 6 lines
Quoted 6 lines

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.

Quoted 7 lines
Quoted 1 line

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

Quoted 3 lines

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

#17 lore raw
In reply to Sam Ravnborg
Quoted 2 lines · Sam Ravnborg

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

Documentation/kbuild/makefiles.txt file will be used. · line 91

Quoted 13 lines

+=== Goal definitions

Documentation/kbuild/makefiles.txt +12 -0
+
+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

#18 lore raw
In reply to Sam Ravnborg
Quoted 15 lines · On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:
Quoted 3 lines

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)

Quoted 4 lines

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

Quoted 6 lines
Quoted 1 line

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

Quoted 11 lines

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

Quoted 8 lines

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

#19 lore raw
Quoted 5 lines

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.

Quoted 1 line

Could it be automated?

For text with a unifom structure like makefiles.txt - yes.

Sam

#20 lore raw
In reply to Sam Ravnborg
Quoted 15 lines · On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:
Quoted 3 lines

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)

Quoted 4 lines

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

Quoted 6 lines
Quoted 1 line

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

Quoted 11 lines

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

Quoted 8 lines

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

#21 lore raw
In reply to Sam Ravnborg

* Date: Fri, 10 Aug 2007 09:40:47 +0200
* Sam Ravnborg:

Quoted 7 lines

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

#22 lore raw
In reply to Stephen Hemminger
Quoted 4 lines · 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.

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

#23 lore raw
In reply to Stephen Hemminger
Quoted 2 lines · Stephen Hemminger

Advantages of html:
* basic formatting like lists, italics, etc

Plaintext has lists too. See for example <[email protected]>. ;-)

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

Quoted 1 line

* easier to integrate into other places and retain formatting

Out-of-tree places?

Quoted 1 line

* ability to link documents and to external sources easier

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

Quoted 4 lines

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

Indeed.

Signature · 3 lines
Stefan Richter
-=====-=-=== =--- -=--=
http://arcgraph.de/sr/
#24 lore raw
Quoted 23 lines · Stefan Richter
Quoted 2 lines · Stephen Hemminger

Advantages of html:
* basic formatting like lists, italics, etc

Plaintext has lists too. See for example <[email protected]>. ;-)

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

Quoted 1 line

* easier to integrate into other places and retain formatting

Out-of-tree places?

Quoted 1 line

* ability to link documents and to external sources easier

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

Quoted 4 lines

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

Quoted 11 lines

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 [email protected]
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.

Signature · 1 line
Brennan Ashton
#25 lore raw
In reply to Stephen Hemminger
Quoted 7 lines · 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

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

/italic text/
*bold text*
_underlined text_

Quoted 1 line

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

Quoted 1 line

* 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/ ?

Quoted 3 lines

Downsides:
* can become too formatted and unclear

Yup.

Quoted 1 line

* accessibility and translation issues?

Those exist whatever format you pick.

Quoted 1 line

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

Signature · 3 lines
Jesper Juhl <[email protected]>
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
#26 lore raw
Quoted 9 lines · Jesper Juhl
Quoted 7 lines · 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

Quoted 7 lines

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

/italic text/
*bold text*
_underlined text_

This is likely to generate false positives.

Jan

#27 lore raw
In reply to Stephen Hemminger

Hi Stephen,

Quoted 4 lines · 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.

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

#28 lore raw
Quoted 4 lines · Willy Tarreau

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:

Quoted 6 lines

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.

#29 lore raw
Quoted 18 lines · J. Bruce Fields
Quoted 4 lines · Willy Tarreau

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:

Quoted 6 lines

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

Quoted 5 lines

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

#30 lore raw
Quoted 5 lines

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

#31 lore raw
Quoted 9 lines · Sam Ravnborg
Quoted 5 lines

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.

Quoted 1 line

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.

Quoted 2 lines

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

#32 lore raw
In reply to Willy Tarreau
Quoted 4 lines · Willy Tarreau

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.

#33 lore raw
Quoted 10 lines · J. Bruce Fields
Quoted 4 lines · Willy Tarreau

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.

Quoted 5 lines

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

#34 lore raw
Quoted 17 lines · On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
Quoted 10 lines · J. Bruce Fields
Quoted 4 lines · Willy Tarreau

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.

Quoted 5 lines

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?

Quoted 6 lines

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

#35 lore raw
Quoted 14 lines · Randy Dunlap
Quoted 6 lines · On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
Quoted 5 lines · J. Bruce Fields

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?

Quoted 6 lines

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.

Quoted 3 lines

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.

Signature · 3 lines
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
#36 lore raw
Quoted 3 lines · Stefan Richter

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

#37 lore raw
Quoted 7 lines · Sam Ravnborg
Quoted 2 lines · Stefan Richter

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.

Quoted 2 lines

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

Signature · 3 lines
Stefan Richter
-=====-=-=== =--- -==--
http://arcgraph.de/sr/
#38 lore raw
In reply to Willy Tarreau
Quoted 17 lines · On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote:
Quoted 10 lines · J. Bruce Fields
Quoted 4 lines · Willy Tarreau

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.

Quoted 5 lines

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?

Quoted 6 lines

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

#39 lore raw
In reply to Willy Tarreau
Quoted 16 lines · On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:

Hi Stephen,

Quoted 4 lines · 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.

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.

Quoted 3 lines

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

Quoted 10 lines

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

#40 lore raw
In reply to Willy Tarreau
Quoted 16 lines · On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote:

Hi Stephen,

Quoted 4 lines · 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.

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.

Quoted 3 lines

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

Quoted 10 lines

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