From owner-freebsd-doc@FreeBSD.ORG Mon Apr 1 05:29:30 2013 Return-Path: Delivered-To: docs@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 95E17B7F for ; Mon, 1 Apr 2013 05:29:30 +0000 (UTC) (envelope-from m.e.sanliturk@gmail.com) Received: from mail-ve0-f173.google.com (mail-ve0-f173.google.com [209.85.128.173]) by mx1.freebsd.org (Postfix) with ESMTP id 5A923A2A for ; Mon, 1 Apr 2013 05:29:30 +0000 (UTC) Received: by mail-ve0-f173.google.com with SMTP id cy12so2176725veb.18 for ; Sun, 31 Mar 2013 22:29:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type; bh=dD8Fhtnw++EJobi6fbeM5bJ3zWZj41pWgcWnAgFo3JI=; b=WDKwtzmpVClSqULCCqPlBvVOo9RsNjZ/Pp72rcS4ERV0brZLiSP0XAEns5tdG5Cqwv t+YmimvNCDon7xKDGDGQy3GxsuUv4SkBAYBbM+gN96XB25I3Wq+I/aR0ji/YebTbGdTE 9KTg9n+g45keM2uPR9lNAwSKH/mqgFzbqkmbOHULtct5Anus4FoS6+qb2tLXSdSSPcO0 CsCCNN42FdWHvGaY1jJWeFICkumWI7Qr7/gvt/YIB+Akko+P07AmfLcBTb+EI2fNr3Kq piohdhZkRBj4UmBxAMXKZkJiDGGiHkK0l0O80iE7Q8p599oxGgCzuHGIGs8wODIJFvwQ FvUg== MIME-Version: 1.0 X-Received: by 10.58.40.9 with SMTP id t9mr8312595vek.10.1364794163671; Sun, 31 Mar 2013 22:29:23 -0700 (PDT) Received: by 10.58.132.203 with HTTP; Sun, 31 Mar 2013 22:29:23 -0700 (PDT) In-Reply-To: References: Date: Sun, 31 Mar 2013 22:29:23 -0700 Message-ID: Subject: Re: a proposal for the FAQ From: Mehmet Erol Sanliturk To: Eitan Adler Content-Type: text/plain; charset=UTF-8 X-Content-Filtered-By: Mailman/MimeDel 2.1.14 Cc: docs@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 01 Apr 2013 05:29:30 -0000 On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler 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