a proposal for the FAQ

[Frank Leonhardt]

On 01/04/2013 06:29, Mehmet Erol Sanliturk wrote:
> On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler <lists at 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
>

This idea has some merit, but I don't think converting everything to 
HTML is the best choice. It's a fluid standard, and, the assertions of 
web designers not withstanding, it's NOT a programming language and 
therefore unable to cope with all eventualities. And that's before HTML5 
becomes mainstream (any news on the lynx embedded video update?)

Might I suggest using a proper language that everyone knows? The choice 
is obviously 'C'. I did think of C++, but it's too obfuscated if used 
incorrectly whereas C is explicit. Better yet, mandate K+R 'C' to avoid 
possible cross-platform compatibility problems (is gc++ completely 
compatible with CLANG?)

If the actual content was placed a string constants in the data segment 
it would be easy enough to have platform-specific code output it in the 
correct form - man pages, HTML or whatever you like - including in new 
standards not yet dreamt up - by simply writing a new output function, 
and conditionals become a breeze. And the best bit is you could put a 
rudimentary language translation system layer between the data and the 
output function, getting rid of the translation problem at the same 
time. (Okay, I realise machine translation isn't the whole answer, but 
users could select the latest machine translation or the 
human-translated version if they didn't mind it being a bit out-of-date).

Regards, Frank.