From owner-freebsd-doc@FreeBSD.ORG Tue May 28 21:06:20 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 796AA70D for ; Tue, 28 May 2013 21:06:20 +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 39E3C94C for ; Tue, 28 May 2013 21:06:20 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 7577514D250D for ; Tue, 28 May 2013 23:06:13 +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 tb5fM-D8lV54 for ; Tue, 28 May 2013 23:06:08 +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 B8AFD14D2403 for ; Tue, 28 May 2013 23:06:08 +0200 (CEST) Message-ID: <51A51C40.1030205@FreeBSD.org> Date: Tue, 28 May 2013 23:06:08 +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: doc@freebsd.org Subject: Re: RFC: Upgrading to DocBook 5.0 References: <519FA4FE.4030305@FreeBSD.org> In-Reply-To: <519FA4FE.4030305@FreeBSD.org> 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: Tue, 28 May 2013 21:06:20 -0000 Em 24-05-2013 19:35, Gabor Kovesdan escreveu: > I'm working on upgrading our documentation set to DocBook 5.0 and I'd > like to discuss some details. We have some customizations and strange > uses, which can be expressed with DocBook 5.0's own vocabulary. This > upgrade is a good opportunity to change these, as well. I propose the > following changes in our vocabulary: > > DocBook 5.0 has a systemitem element, which expresses actors of a > human-system interactions. This has the class attribute to further > classify the actor. Alternatively, we can just mark up each of them as > systemitem without class attributes since they are not distinguished > in rendering. Actually, I tend to prefer this solution since it > simplifies the markup and thus lowers the learning curve of DocBook, > which is often criticized by people, who would prefer markdown or > wiki-style documentation. > username --> systemitem class="username" > groupname --> systemitem class="groupname" > hostid role="fqdn" --> systemitem class="fqdomainname" > hostid role="hostname" --> systemitem class="fqdomainname" > hostid role="domainname" --> systemitem class="fqdomainname" > hostid role="netmask" --> systemitem class="netmask" > hostid role="mac" --> systemitem class="etheraddress" > hostid role="ipaddr" --> systemitem class="ipaddress" > hostid --> systemitem > > This is actually a type of file and the filename class attribute may > also be devicefile, which expresses its semantics. Again, we should > consider dropping the class attributes to simplify things: > devicename --> filename class="devicefile" > > These are not actually distinguished in formatting and the package > element expresses them better: > filename role="package" --> package > filename role="port" --> package I have a patch to preview how it would look like: http://kovesdan.org/patches/fbsd-docbook5.diff Please comment on this. It is very important to discuss this kind of changes. Thanks, Gabor