On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler <li...@eitanadler.com> wrote:
Hi all,
Over the past several months I have been working on a project called
ThwackAFAQ. For those who don't know this project has been to review,
edit, and rewrite the FAQ to be relevant to the modern day.
I've removed references to hardware that hasn't been sold in over 10
years or to software features that reached their EoL in FreeBSD 2.x.
At this date I feel the project has reached a level of maturity such
that it makes sense to write this email:
I propose that we merge the handbook into the FAQ.
While they both cover the same material the handbook source is over
83892 lines of XML while the FAQ is now at a measly 8242 lines.
Further the FAQ is in bite sized chunks while the FAQ requires lots of
tedious reading. Translators currently have issues keeping up with
the pace of changes in both books, and must translate the same basic
content twice. If only we could have one clear and canonical source
for translators to work with.
Sure there are some topics not covered in the same depth in the FAQ
but many Linux distributions solve this in a very nice way: distribute
the details and extraneous items to bloggers and tip writers. This
releases us, the doc team, from all the extra work of writing and fact
checking things that will no longer be true in the next version of
FreeBSD. Not only that but it even generates more content for the
front page where we publish articles written about the operating
system.
Over the next few weeks (as soon as the doc slush ends) I intend to
move the last few remaining portions of the handbook into the FAQ and
commit the removal of the handbook once and for all.
--
Eitan Adler
Since a work is continuing on documentation , I want to make a more , let's
say , radical or encompassing steps as follows :
The Handbook and the other documents is in another directory with respect
to head in SVN .
Many times , I have expressed the idea that this is causing much trouble
because the Handbook is maintained for three releases with a lot of IF
statements about releases . At present , there is NO any Handbook for the
HEAD ( or Current ) . To make or suggest any idea about the Handbook is
very difficult because it requires knowledge of at least four releases . A
person starting from Version 9.0 may not have much idea about previous
releases . Therefore , it is very likely that there will not be much
suggestions to improve .
Another problem is manual pages : These are in ROFF , but the other
documents are in , now , XML .
I searched to find a ROFF to XML converter , but I could not find one .
My opinion is to convert ALL of them to HTML and disperse the Handbook
pages into HEAD directories where they are related with manual pages .
This conversion will eliminate the requirement of knowing three , let's say
, languages :
ROFF , XML , HTML .
It is very likely that number of such people is very small .
At the same time , it will remove necessity of generating HTML from XML .
If I am wrong , please , forgive me , because , the Handbook is in XML in
SVN , but , it is HTML in the web site .
Manual pages are ROFF in SVN , but in HTML in web site .
After such conversion , prepare appendixes to list and reference to manual
pages easily because they will also be in HTML .
When a modification patch is suggested by developers , it will contain
modifications to both manual pages and related Handbook pages .
If the same patch is applied to previous releases , also at the same time .
manuals and Handbook of that version will also be updated .
This means that such a dispersion into the HEAD will NOT increase the
required effort , but it will reduce it actually .
Many programs in the base are displaying error messages when command line
parameters contain errors .
Since manuals will be in HTML format , instead of listing errors in spite
of the manual , by calling a routine to display manual is much more easy
and it will supply much more correct information only with ONE application .
It is NOT necessary to compress the manual pages to make them conform to
"man" program :
With respect to my understanding , "man" is a script .
When "man page" is specified to list the manual page , it may check
"page.html" : If it exists , it forks a HTML displayer with the advantage
that the referenced pages also may be displayed easily .
If "page.html" does not exist , it may use its current form .
There are some , for example , "ifconfig , mount , ..." , programs that
when any command line parameter is not supplied , it is doing a prescribed
default behavior . All of these programs may be modified to request the
default behavior with a command line parameter .
The current scripts using these programs are in source form : They may be
easily modified .
When a release is branched , everything related to documents also will be
branched ,
and it will be very easy to modify them with the current works , because
such modifications will not be make any effect on the existing release
documentation .
In the web site , only current manual pages are accessible :
With respect to my suggestion , the documentation page in the website may
be as follows :
Handbook for Version 10.0
Handbook for Version 9.2
Handbook for Previous Versions ( 8.4 , 9.1 )
Since manual pages will be made appendixes to the Handbook , actually it is
not necessary to supply additional links to them , but their links may be
similar to the ones above .
Over time , this page will supply ALL documentation links to previous
versions , where last version is inserted top of the list .
Since the Handbook is in HTML form , it may be incorporated into a content
management system like a blog and integrated with some selected mailing
lists for some parts :
When users do not understand one point , they may enter question , or they
may suggest an improvement . In that way , the Handbook and manual pages
will be improved and updated collectively : The links to messages in
mailing lists will be appended to the Handbook pages , and over time ,
questions and information supplied in answers may be transferred to
Handbook pages .
This will make the Handbook comprehensive as much as possible , and
eliminate being outdated over time due to separate maintenance of it .
Thank you very much .
Mehmet Erol Sanliturk
