On 04.09.22 17:39, Alvaro Herrera wrote:
What changes? I doubt we'll want to adopt a new version immediately after release, since we want to stay compatible with older systems.
The migration isn't a matter of days. It's a huge step because nearly all files are touched and we have to act carefully to deliver (nearly) identical HTML, PDF, ... files as before. As a preview of the ongoing the actual README.md file is attached.
Jürgen Purtz
Migration of PG's documentation from DocBook 4.5 to DocBook 5.2 =============================================================== The migration from DocBook 4.x to 5.x is a huge step which changes most of PG's sgml-files. DocBook supports the migration with some scripts, but PG's documentation doesn't meet all prerequisites. Therefore we use - in addition to DocBook's scripts - some bash and sed commands to overcome the problems. In addition, we need a lot of small detailed changes to many sgml-files. This is more or less individual manual work. To be able to perform such changes at any point in time, the changes are done with Perl scripts per file. Major DocBook changes --------------------- - Discontinuation of a DOCTYPE declaration. Instead, there is an XML conforming namespace which uniquely identifies DocBook tags. - Discontinuation of DTDs (and XSD schema). Instead, the validation is done against a RELAX NG schema. - Some tag names change, especially to adopt the XML conventions and standards. The content model of some tags is narrowed down and defined more precise. Migration steps --------------- The migration is steered by conv.sh. The script uses 3 directories: All scripts and other necessary information is located in **$ToolDir**, the existing sgml-files are located in **$FromSgmlDir**, the migrated ones are in **$ToSgmlDir**. 1. Preparation: The git tree of the complete PG source is copied to a different place. So we can use git after any intermediate step to check the changes. 2. Migration: Some standard modifications to every single file to make them XML conform. Few individual changes per file. Perform the standard DocBook migration. 3. Changes: Perform some standard changes on few files. Perform many individual changes on many files. 4. Validation: Perform validation against the RELAX NG schema. Introduction of a new tool -------------------------- In the past, we used the tool **xmllint** to validate the sgml files against the DocBook DTD. This worked well. Also, its validation against a RELAX NG schema works well as far as no schema-validation occurs. But if the RELAX NG schema is violated by an sgml file, the resulting error messages are more confusing than helpful. Therefore, we should consider to introduce another validator. During the migration phase, we have used **jing**. It's Java, it's fast, the error messages are very precise. But there are many others: https://relaxng.org/#validators. Should we possibly provide multiple validators in doc/src/sgml/Makefile? ToDo ---- - Adoption of doc/src/sgml/Makefile - Additional CSS definitions ??? - Adoption of Appendix J: Documentation Forecast -------- - Entities: We use **character entities** (e.g.: \—) as well as **parameter entities** (e.g.: %filelist;). The use of character entities instead of hex-values or direct Unicode-values is helpful because it supports the readability of the source for authors. The use of parameter entities can be replaced by the more XML-conform XInclude mechanism. But this isn't possible without major changes in most files: - Every xml/sgml-file must be XML conform, especially it needs a single root element. - In every xml/sgml-file we must re-declare namespace(s). The reason is that parameter entities perform a plain text substitution whereas xi:include creates trees and combines them. - Description of user- and program-interfaces: We use a confusing mixture of <synopsis>, <function>, <command>, <cmdsynopsis> (but not <funcsynopsis>), <optional>, and '[]'. We shall work on the unification of this diversity by creating some rules (like README.links) and then - more or less manually - change the source code over time.
