From owner-freebsd-doc@FreeBSD.ORG Fri May 24 17:36:04 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id D69F7C75; Fri, 24 May 2013 17:36:04 +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 94F0C335; Fri, 24 May 2013 17:36:04 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 623C214D242E; Fri, 24 May 2013 19:36:03 +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 Czj7k3bW8PVp; Fri, 24 May 2013 19:35:56 +0200 (CEST) Received: from [152.66.171.63] (dhcp-831.q.wlan.net.bme.hu [152.66.171.63]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id F41AD14D242C; Fri, 24 May 2013 19:35:55 +0200 (CEST) Message-ID: <519FA4FE.4030305@FreeBSD.org> Date: Fri, 24 May 2013 19:35:58 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:21.0) Gecko/20100101 Thunderbird/21.0 MIME-Version: 1.0 To: doc@freebsd.org Subject: RFC: Upgrading to DocBook 5.0 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: Fri, 24 May 2013 17:36:04 -0000 Hi, 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 Comments are welcome. Thanks, Gabor