From owner-freebsd-doc@FreeBSD.ORG Fri Mar 15 07:42:05 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 4AC14634 for ; Fri, 15 Mar 2013 07:42:05 +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 D5A7A825 for ; Fri, 15 Mar 2013 07:42:04 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 1074A14D242F; Fri, 15 Mar 2013 08:42:03 +0100 (CET) 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 ZnITvw2usYSX; Fri, 15 Mar 2013 08:42:02 +0100 (CET) Received: from [192.168.1.100] (5403A6BE.catv.pool.telekom.hu [84.3.166.190]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id 6746114D242D; Fri, 15 Mar 2013 08:42:02 +0100 (CET) Message-ID: <5142D0C9.70905@FreeBSD.org> Date: Fri, 15 Mar 2013 08:42:01 +0100 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:17.0) Gecko/20130307 Thunderbird/17.0.4 MIME-Version: 1.0 To: Warren Block Subject: Re: [CFR] Migrating the documentation to a real XML toolchain References: <512D2F9C.8080403@FreeBSD.org> <5142357A.9070301@FreeBSD.org> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Cc: doc@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: Fri, 15 Mar 2013 07:42:05 -0000 Em 15-03-2013 00:33, Warren Block escreveu: > On Thu, 14 Mar 2013, Gabor Kovesdan wrote: > >> Em 27-02-2013 02:24, Warren Block escreveu: >>> Author info is a little off. Compare the authors at the start of >>> the bsdinstall chapter: >>> http://people.freebsd.org/~gabor/db45/en_US.ISO8859-1/books/handbook/bsdinstall.html >>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/bsdinstall.html >>> >>> >>> In the standard version, each section is rendered as a sentence, >>> with multiple authors separated by commas. >>> >>> Acronyms don't have any highlights, they just look like normal text. >>> >> Thank you Warren for the exhaustive list, I've been fixing the issues >> you reported. However, I don't find highlighted acronyms in the old >> rendering either. Could you please point me to a concrete example, >> please? > > Good question. I know this is given as a reason why acronyms should > always be marked up, and I thought I'd seen it at some point in the > FreeBSD docs. But it does not do it now, and I may have been looking > at something else. It is something that would really benefit the reader. I also agree that it would be a nice feature but actually I don't even understand how it is supposed to work at the moment. In most cases, the markup does not hold the expansion, it just says e.g. NFS but does not include what it needs to expand to. We could add an attribute but then it would only appear if the attribute is present. Shall we expand all occurrences (would mean lots of redundancy) or just the first? Other idea would be to use a separate XML database of acronym expansions, install it with the docs and let JavaScript rewrite the acronyms. But in this case we have to think of how to handle acronyms that can have multiple expansions. Gabor