From owner-freebsd-doc@FreeBSD.ORG Thu Aug 30 15:53:14 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 595FE106566B; Thu, 30 Aug 2012 15:53:14 +0000 (UTC) (envelope-from hrs@FreeBSD.org) Received: from mail.allbsd.org (gatekeeper.allbsd.org [IPv6:2001:2f0:104:e001::32]) by mx1.freebsd.org (Postfix) with ESMTP id CAB018FC1B; Thu, 30 Aug 2012 15:53:13 +0000 (UTC) Received: from alph.allbsd.org (p3048-ipbf1204funabasi.chiba.ocn.ne.jp [123.218.144.48]) (authenticated bits=128) by mail.allbsd.org (8.14.5/8.14.5) with ESMTP id q7UFqvsi096739 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 31 Aug 2012 00:53:07 +0900 (JST) (envelope-from hrs@FreeBSD.org) Received: from localhost (localhost [127.0.0.1]) (authenticated bits=0) by alph.allbsd.org (8.14.5/8.14.5) with ESMTP id q7UFqu3S098112; Fri, 31 Aug 2012 00:52:56 +0900 (JST) (envelope-from hrs@FreeBSD.org) Date: Fri, 31 Aug 2012 00:52:44 +0900 (JST) Message-Id: <20120831.005244.2295575122657925960.hrs@allbsd.org> To: gabor@FreeBSD.org From: Hiroki Sato In-Reply-To: <503E7E70.2050504@FreeBSD.org> References: <50392481.1070708@FreeBSD.org> <20120829.221019.266908030257017857.hrs@allbsd.org> <503E7E70.2050504@FreeBSD.org> X-PGPkey-fingerprint: BDB3 443F A5DD B3D0 A530 FFD7 4F2C D3D8 2793 CF2D X-Mailer: Mew version 6.5 on Emacs 23.4 / Mule 6.0 (HANACHIRUSATO) Mime-Version: 1.0 Content-Type: Multipart/Signed; protocol="application/pgp-signature"; micalg=pgp-sha1; boundary="--Security_Multipart(Fri_Aug_31_00_52_44_2012_228)--" Content-Transfer-Encoding: 7bit X-Virus-Scanned: clamav-milter 0.97.4 at gatekeeper.allbsd.org X-Virus-Status: Clean X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (mail.allbsd.org [133.31.130.32]); Fri, 31 Aug 2012 00:53:07 +0900 (JST) X-Spam-Status: No, score=-96.8 required=13.0 tests=CONTENT_TYPE_PRESENT, ONLY1HOPDIRECT, RCVD_IN_RP_RNBL, SAMEHELOBY2HOP, USER_IN_WHITELIST autolearn=no version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on gatekeeper.allbsd.org 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: Thu, 30 Aug 2012 15:53:14 -0000 ----Security_Multipart(Fri_Aug_31_00_52_44_2012_228)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Gabor Kovesdan wrote in <503E7E70.2050504@FreeBSD.org>: ga> Em 29-08-2012 15:10, Hiroki Sato escreveu: ga> > 1. Convert ids to upper-case and use them. No compatibility ga> > problem. ga> > ga> > 2. Use lower-case ids. Links from pages outside of ga> > www.FreeBSD.org may be broken. ga> > ga> > 3. Convert the existing ids to upper-case but use lower case for ga> > newly-added ones. It works but not consistent. ga> ga> 4. Use some kind of redirection at the HTTP level. Let's forget about HTTP level solution. On the mirror servers it does not work. ga> I'd prefer (2) or (4). I think we already carry a lot of legacy stuff ga> and people frequently come up with the idea of using some kind of ga> markdown or wiki system for documentation and try to recruit more ga> people to support this idea because the current situation is much more ga> complicated than it could. I think going to XML and dropping character ga> entities highly helps people writing docs and simplifying things. So ga> I'd prefer avoiding one more not really sensible policy and confusion ga> factor. Using upper-case names affects readability and suggests that ga> it is a policy or a practice to follow even if we go for (3). Besides, ga> please take into account that we never care of broken links when we ga> remove a chapter or section and that links may still bring you to the ga> proper page just not to the proper part. The user may still find the ga> part she is looking for. One compromise solution would be adding an additional anchor with upper-case ids just after the normal (lower-case) one by XSLT only for HTML output. It is relatively easy and should not be harmful. How about this? Hmm, I agree that upper-case ids are annoying but cannot agree that we never took care of anchors and/or we can ignore the negative impact from changing them. We should take care of them as far as we can. Just converting them to lower-case is different from the case of removal of a section because it is not non-avoidable. -- Hiroki ----Security_Multipart(Fri_Aug_31_00_52_44_2012_228)-- Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (FreeBSD) iEYEABECAAYFAlA/jEwACgkQTyzT2CeTzy1XHACcCidtyMHazJ6LnmTwZgFZ4fiN NaYAniOOBJsulR4QPFC3cEX35WnHGDfx =Wy1g -----END PGP SIGNATURE----- ----Security_Multipart(Fri_Aug_31_00_52_44_2012_228)----