From owner-freebsd-doc@FreeBSD.ORG  Wed Jul 10 07:41:32 2013
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
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 3DA4D55B;
 Wed, 10 Jul 2013 07:41:32 +0000 (UTC)
 (envelope-from amijaresp@gmail.com)
Received: from mail-ve0-x22c.google.com (mail-ve0-x22c.google.com
 [IPv6:2607:f8b0:400c:c01::22c])
 by mx1.freebsd.org (Postfix) with ESMTP id E58A019EA;
 Wed, 10 Jul 2013 07:41:31 +0000 (UTC)
Received: by mail-ve0-f172.google.com with SMTP id jz10so5443355veb.3
 for <multiple recipients>; Wed, 10 Jul 2013 00:41:31 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113;
 h=mime-version:in-reply-to:references:date:message-id:subject:from:to
 :cc:content-type;
 bh=SonU6YlhzLqlKv6G8zu9lSd+DED0gvY29qUGKluzBhs=;
 b=hObclFnmt6feX84JULJnAl7ZRdui52XujeMMt2rU9NQ7Y515kO7CZ+h1oEp9UnmdMs
 4FjZPLDkdNb1iQ8+hg4Uw7HRaYyMD27AGhYMveSdJcIrMeDf50R9rNTKxiurqCiAdZMI
 NYsWx0wknpimV+PBwLcJ2Y4iDvSKU1kWTAT892sSWfwjLtY8Ey6wFlTF83DCFM9CL4y3
 mMbNHOvcasoqz7XIRSOoCiWBHVkjoH0ClBg81IztC53WJJVRvxsaUKgUdTxUeTdo+no0
 V9QZQ1oecqr8s8SG0gJQQXVtP7q0IX2xjmrJ0pkeE5jUeg2sII7j8VEkoF239els8Iwb
 YUBA==
MIME-Version: 1.0
X-Received: by 10.58.227.198 with SMTP id sc6mr18467813vec.59.1373442091450;
 Wed, 10 Jul 2013 00:41:31 -0700 (PDT)
Received: by 10.58.224.7 with HTTP; Wed, 10 Jul 2013 00:41:31 -0700 (PDT)
In-Reply-To: <alpine.BSF.2.00.1307091151000.46436@wonkity.com>
References: <519FA4FE.4030305@FreeBSD.org> <51D3E051.5070506@FreeBSD.org>
 <CAGZBXN8dLmf6iuCpD4cw5zbOP-NLj+RqqxtndRa9rAvScSo3Ag@mail.gmail.com>
 <alpine.BSF.2.00.1307091151000.46436@wonkity.com>
Date: Wed, 10 Jul 2013 03:11:31 -0430
Message-ID: <CAGZBXN_aJhg1U=tJ+cV+SRwpy6p8j2DX5mz_F-JHZz7gHYnrUw@mail.gmail.com>
Subject: Re: RFC: Upgrading to DocBook 5.0
From: Alberto Mijares <amijaresp@gmail.com>
To: Warren Block <wblock@wonkity.com>
Content-Type: text/plain; charset=UTF-8
Cc: doc@freebsd.org, Gabor Kovesdan <gabor@freebsd.org>
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Wed, 10 Jul 2013 07:41:32 -0000

>>> One more thing to discuss: shall we maintain the sect1, sect2, ...
>>> elements
>>> or just use section? The section element can have another section element
>>> embedded and the numbering in the rendered version is inferred by the
>>> level
>>> of embedment. This is more uniform and less redundant. In own docs that I
>>> write with DocBook I only use section and it works fine. Opinions?
>
>
>> IMHO, is a good thing to keep a visual clue of the level you are going
>> down while writing.
>
>
> Yes, but that is what the indentation also does.

I agree. However, since humans identify characters much better than
they do with indentation, using sect1 and so is a help for those who
want to improve documentation.

Using only <section> may be confusing for some people and I don't see
the win with changing that.

>
>
>> So, <sect[123...]> should be kept, I think.
>
>
> But it is another thing the user has to track.


I'm not a very experienced docbook user but an occasional one, and I
can tell you this is not a big deal to track with.

It's just my opinion.

Regards,


Alberto Mijares