Date: Thu, 4 Apr 2013 20:29:29 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Gabor Kovesdan <gabor@FreeBSD.org> Cc: doc@freebsd.org Subject: Re: [CFR] Migrating the documentation to a real XML toolchain Message-ID: <alpine.BSF.2.00.1304041952140.38333@wonkity.com> In-Reply-To: <515DDE5E.1070405@FreeBSD.org> References: <512D2F9C.8080403@FreeBSD.org> <515DDE5E.1070405@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 4 Apr 2013, Gabor Kovesdan wrote: > Em 26-02-2013 22:56, Gabor Kovesdan escreveu: >> I have some improvements for the doc infrastructures in the xml-tools >> branch. I think that the changeset is now getting mature enough to be >> merged back so I'd like to ask for review. It does not affect the web >> pages, only books and articles. The rendered docs are available at: >> http://people.freebsd.org/~gabor/db45/ >> >> For every article/book, you will find there the chunked XHTML docs or if >> you manually enter the URL, you can access the single XHTML and PDF >> versions as (article|book)\.(html|pdf). > > Thank you for all the feedback I got! I've fixed the problems reported and > the regenerated result is online at the same location. > > I'm still encouraging you to review it again and check if you find something > broken. The new rendering process is quite different from the old one so > there are differences in the output (e.g. whether the navigation > header/footer has numbered chapter titles or not). Please report only > differences that are clearly wrong or those that you think that are worse in > the new output and do not report just the fact that something differs. Looking at the HTML Handbook: The copyright in the original is a link, but is not in the new version. Not sure how important that might be. After the two legal notice links at the start, there is a "February 1999" text in the new version. Links to other chapters are better in the new version. It shows the chapter number but also the title. Nice! The callouts don't line up the same in these two sections: New: http://people.freebsd.org/~gabor/db45/en_US.ISO8859-1/books/handbook/bsdinstall-start.html#idp67265936 Old: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/bsdinstall-start.html#AEN1480 Could be a whitespace parsing issue, or just a change in the source that has not been copied over. I didn't see any serious problems in a quick look. There are some minor formatting differences, spacing in tables and such, but the new version looks okay to me. PDF Handbook: Some links show a relative path rather than a URL. From page 2 of the PDF: You may also want to search the handbook (../../../../search/index.html). Some bulleted lists are shown with the bullet on a blank line (actual page 23, logical page 3). Indents on author attributions which should probably not be there (actual page 30, logical page 10). Graphic images are not scaled down to fit the page width. See actual page 37, logical page 17 for an example. Text in some elements (<screen>?) is not wrapped, but the old version did not do that either (actual page 38, logical page 18). Using a somewhat smaller font for these would help. That's enough for now, I think. Thanks again for your work on this!
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1304041952140.38333>