From owner-freebsd-doc@FreeBSD.ORG Wed Jun 19 10:57:46 2013 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id D40A310F for ; Wed, 19 Jun 2013 10:57:46 +0000 (UTC) (envelope-from gabor@FreeBSD.org) Received: from server.mypc.hu (server.mypc.hu [87.229.73.95]) by mx1.freebsd.org (Postfix) with ESMTP id 9274F18EF for ; Wed, 19 Jun 2013 10:57:46 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 7E0A514D250A; Wed, 19 Jun 2013 12:57:45 +0200 (CEST) X-Virus-Scanned: amavisd-new at !change-mydomain-variable!.example.com Received: from server.mypc.hu ([127.0.0.1]) by server.mypc.hu (server.mypc.hu [127.0.0.1]) (amavisd-new, port 10024) with LMTP id EHMV9ccUDFb7; Wed, 19 Jun 2013 12:57:40 +0200 (CEST) Received: from [192.168.0.10] (54034B4D.catv.pool.telekom.hu [84.3.75.77]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id 8330514D242E; Wed, 19 Jun 2013 12:57:40 +0200 (CEST) Message-ID: <51C18EA4.7030108@FreeBSD.org> Date: Wed, 19 Jun 2013 12:57:40 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:22.0) Gecko/20100101 Thunderbird/22.0 MIME-Version: 1.0 To: Dru Lavigne , freebsd-doc@freebsd.org Subject: Re: RFC: Upgrading to DocBook 5.0 References: <1371499528.97592.YahooMailClassic@web184906.mail.gq1.yahoo.com> In-Reply-To: <1371499528.97592.YahooMailClassic@web184906.mail.gq1.yahoo.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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: Wed, 19 Jun 2013 10:57:46 -0000 Em 17-06-2013 22:05, Dru Lavigne escreveu: > Can we have a summary for the FDP (and for the benefit of Handbook editors) of when/if systemitem class= should be used? Are there also systemitems for the different types of s which should be used instead? The systemitem element is documented well here: http://www.docbook.org/tdg5/en/html/systemitem.html When to specify the class atttribute is our decision and as you see, there are different preferences. And it is important to note that at the moment we are using our extensions and will only be used once we upgrade to DB 5.0. So the documentation should not be updated with this in head but in db5. As for filename, it will be still and we already use correctly the class names, yet it should be documented. The DocBook reference is here: http://www.docbook.org/tdg5/en/html/filename.html As for the FDP, it is another item, which we have to solve. I have some ideas in my mind but I haven't got there yet so I haven't started a discussion. First, I would like to more clearly separate it into 2-3 parts: 1, A technology introduction: XML, XHTML, DocBook, XSLT. A concise introduction to the ideas behind these technologies and how they can be used for technical documentation. I think it should be like a tutorial, which includes references but it's no use trying to create another XML, XHTML or DocBook reference. It should be limited to the minimal knowledge that is necessary to get started with our docs. 2, How we use these technologies in our documentation set, i.e. the FreeBSD-specific things. One with previous knowledge in DocBook would be able to start reading here. It could fit here whether we use classes on systemitems and how our .mk files work, etc. 3, The FreeBSD writing style. General advices, spelling, etc. Gabor