From owner-freebsd-doc@FreeBSD.ORG Fri Aug 3 11:13:05 2012 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 3814A106567B; Fri, 3 Aug 2012 11:13: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 A0C1B8FC17; Fri, 3 Aug 2012 11:13:04 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id 5EE3714E7E1C; Fri, 3 Aug 2012 13:03:32 +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 5dA1-TUSftjG; Fri, 3 Aug 2012 13:03:25 +0200 (CEST) Received: from [192.168.1.117] (catv-80-98-232-12.catv.broadband.hu [80.98.232.12]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id 4182E14E7E1B; Fri, 3 Aug 2012 13:03:25 +0200 (CEST) Message-ID: <501BAFCF.9010600@FreeBSD.org> Date: Fri, 03 Aug 2012 13:02:39 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:14.0) Gecko/20120604 Thunderbird/14.0a2 MIME-Version: 1.0 To: doc@FreeBSD.org Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Cc: www@FreeBSD.org Subject: RFC: doc/www cleanup 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: Fri, 03 Aug 2012 11:13:05 -0000 Hi Doc Fellows, the XML migration that is in progress now, is also a big cleanup that will probably simplify documentation authoring. When working on this item I've encountered several old constructs and several things that made me think of further directions. I'd like to discuss these changes with you before proceeding with them: 1, Removing emacs PSGML comments: PSGML is an emacs mode for SGML editing. It can be instructed to behave in a determined way by SGML comments or separately with a configuration file (described in fdp-primer). Our documentation is scattered by PSGML comments like this: XML requires tags to be closed and attributes to be always quoted so this loses most if its utility and these comments just confuse people, who don't know what they mean. Indenting or any other specific option can be configured in the .emacs file. I propose dropping these comments. 2, Relaxing character entity usage: To be able to read non-ASCII characters on ASCII-only systems, we have been using character entities, like á. But in CJK languages, Greek and Russian every character is non-ASCII so practically they cannot be used nor were they used. So they are only used in ISO-8859 encodings (except Greek, which is also from this family). In fact, displaying these Latin-based characters nowadays isn't that problematic any more. Furthermore, if you edit text in a given language then we can suppose that you understand the language so you know what you should see and you know how to configure your system if you don't see the desired result. As a result, these entities nowadays don't have any real advantage any more but they highly "pollute" the text and make it much harder to edit and read. One exception is using characters in a specific language that aren't present there, e.g. a non-English developer name in the English documentation, etc. So I propose for every translation to convert back entities to normal characters and only conserve those that aren't present in the given language. Abundance of character entities used to mean difficulties for new documentation people, especially for those who don't have that much IT background. This change would make the texts more natural. 3, Preferring XML/XSLT over scripts: Some parts of the web, like the A-Z index and sitemap pages have their own format that is processed with shell scripts. It would be more consistent to use an XML data file with an XSLT stylesheet for this objective. It would give us more flexibility for further changes and would reduce the several different methods we use to generate things. 4, Stricter XHML: I don't propose going directly to XHTML Strict 1.0 but there are very inconsistently marked up
's, 's, etc. I would like to make them more consistent and prefer CSS styling when applicable. There are also empty paragraphs used as line breaks, which should also be eliminated. This would give us a more consistent look and more structure-oriented webpage files. And after the migration, I plan: 5, Identifying obsolete webpages: There are moved pages both in the English pages and translations that only serve for redirection. These pages were moved a very long time ago so any interested party could update her bookmarks. I would like to remove these finally. On the other hand, there are leftovers in translations, i.e. pages that were removed from the English web but not from the translations. I would like to generate a list of them and send patches to translation projects to clean these up. Thanks in advance for your comments, Gabor