Documentation: what sets amateurs & professionals apart...

[sidetone]

A problem for documentation is, that the XML for DocBook schema needs to use its [FONT=Verdana]style sheet[/FONT], not .txt tools, to take care of spacing and presentation. It should be included in FreeBSD XSLT's stylesheet. https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/stylesheets.html

Using the style sheet for formatting will provide better consistency, and ease of use, so all anyone has to master the DocBook schema.

There should be a tool that removes or checks for spacing outside of element tags as an XML file, and just otherwise checks the schema. The text pad or command line editor should continue to be used, however, its submission needs to be checked as an XML file according to its schema, not as a .txt file. XML and its schema are meant to be used with .xml related tools, not .txt related tools. XML and its style sheets are for organization of presentation and data, while .txt specific tools are nowhere as capable.

Also, BSD can have an extension schema of the DocBook markup schema currently used, with commonly used definitions contained in it. The currently used schema lacks regularly used definitions, because it marks them as spelling errors. Elements and attributes can also be improved for BSD specific use. https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup.html

 

[rigoletto@]

Maintain proper documentation about how to compile the Linux kernel would be really cumbersome (assuming you are including the config part and not just about running a few make commands).

The kernel configuration uses a ncurses interface where the information is very confusing, poorly organized, and most options have pretty useless help info. Also if you disable some options other options disappear from that interface, and several times the options disabled has no apparent relation with the option that become hidden (and I am talking about options in complete different sections).

There was a guy on Gentoo who used to maintain a site called kernel-seeds and he used to pre-made a very minimal kernel config file for every single kernel version.

That guy often told the problems he experienced while creating those "seeds", like something in one version must be compiled as module, then in the next dot version must be compiled in kernel, and later another thing just compiled if another option was configured as module, and later everything changes again and nobody knows why those changes happened (including the kernel devs) - and the only way of discovering those was compiling the kernel over and over, until you find what is wrong...

However, one time you set your own config file you can just use make oldconfig to "import" the configuration file for new kernel version. Usually work well, until you hit some problems like I described before.

EDIT:

Apparently, currently there are more than one person doing those kernel seeds (I've not used Linux for more than a year now). Here you find some INFO.