Date: Mon, 01 Apr 2013 14:05:44 +0100 From: Frank Leonhardt <freebsd-doc@fjl.co.uk> To: freebsd-doc@freebsd.org Subject: Re: a proposal for the FAQ Message-ID: <51598628.1060706@fjl.co.uk> In-Reply-To: <CAOgwaMvUJ7k-eP8njER4JYMvdYNyRgmBLOTQvwhHgoUOj3Hodw@mail.gmail.com> References: <CAF6rxgkwV7W3FVrqmvOezsHSFwjU59yd6Ug0C0u7w3GPErtySg@mail.gmail.com> <CAOgwaMvUJ7k-eP8njER4JYMvdYNyRgmBLOTQvwhHgoUOj3Hodw@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 01/04/2013 06:29, Mehmet Erol Sanliturk wrote: > On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler <lists@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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51598628.1060706>