From owner-freebsd-doc@FreeBSD.ORG Wed Aug 29 20:41:28 2012 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 97210106564A; Wed, 29 Aug 2012 20:41:28 +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 454938FC14; Wed, 29 Aug 2012 20:41:28 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 69A7014E7FC6; Wed, 29 Aug 2012 22:41:26 +0200 (CEST) X-Virus-Scanned: amavisd-new at server.mypc.hu 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 9fw99Sk3sjsC; Wed, 29 Aug 2012 22:41:17 +0200 (CEST) Received: from [192.168.1.101] (D94162B4.catv.pool.telekom.hu [217.65.98.180]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id A79D414E7FBF; Wed, 29 Aug 2012 22:41:17 +0200 (CEST) Message-ID: <503E7E70.2050504@FreeBSD.org> Date: Wed, 29 Aug 2012 22:41:20 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:13.0) Gecko/20120614 Thunderbird/13.0.1 MIME-Version: 1.0 To: Hiroki Sato References: <50390426.40604@FreeBSD.org> <20120826.025845.2271349946315727916.hrs@allbsd.org> <50392481.1070708@FreeBSD.org> <20120829.221019.266908030257017857.hrs@allbsd.org> In-Reply-To: <20120829.221019.266908030257017857.hrs@allbsd.org> X-Enigmail-Version: 1.4.3 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Cc: doceng@FreeBSD.org, doc@FreeBSD.org, www@FreeBSD.org Subject: Re: [CALL FOR REVIEW] doc and www converted to XML X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 29 Aug 2012 20:41:28 -0000 Em 29-08-2012 15:10, Hiroki Sato escreveu: > 1. Convert ids to upper-case and use them. No compatibility > problem. > > 2. Use lower-case ids. Links from pages outside of > www.FreeBSD.org may be broken. > > 3. Convert the existing ids to upper-case but use lower case for > newly-added ones. It works but not consistent. 4. Use some kind of redirection at the HTTP level. I'd prefer (2) or (4). I think we already carry a lot of legacy stuff and people frequently come up with the idea of using some kind of markdown or wiki system for documentation and try to recruit more people to support this idea because the current situation is much more complicated than it could. I think going to XML and dropping character entities highly helps people writing docs and simplifying things. So I'd prefer avoiding one more not really sensible policy and confusion factor. Using upper-case names affects readability and suggests that it is a policy or a practice to follow even if we go for (3). Besides, please take into account that we never care of broken links when we remove a chapter or section and that links may still bring you to the proper page just not to the proper part. The user may still find the part she is looking for. This whole thing could be mitigated with some HTTP redirection. We could rewrite http://freebsd.org/doc/\([^#]*\)#\(.*\) to http://freebsd.org/doc/\1#\2 where \2 is converted to lower-case. I'm not sure what www.freebsd.org runs and whether such rewriting is supported but theoretically it should be possible. Gabor