Date: Sat, 29 Jul 2017 23:31:11 +0000 (UTC) From: Benjamin Kaduk <bjk@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50608 - head/en_US.ISO8859-1/htdocs/news/status Message-ID: <201707292331.v6TNVBRs017712@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: bjk Date: Sat Jul 29 23:31:11 2017 New Revision: 50608 URL: https://svnweb.freebsd.org/changeset/doc/50608 Log: Add 2017Q2 entry on $FreeBSD$-string removal from wblock Modified: head/en_US.ISO8859-1/htdocs/news/status/report-2017-04-2017-06.xml Modified: head/en_US.ISO8859-1/htdocs/news/status/report-2017-04-2017-06.xml ============================================================================== --- head/en_US.ISO8859-1/htdocs/news/status/report-2017-04-2017-06.xml Sat Jul 29 21:01:44 2017 (r50607) +++ head/en_US.ISO8859-1/htdocs/news/status/report-2017-04-2017-06.xml Sat Jul 29 23:31:11 2017 (r50608) @@ -2078,4 +2078,91 @@ 219275</a> for details.</task> </help> </project> + + <project cat='doc'> + <title>Doc Version Strings Improved by Their Absence</title> + + <contact> + <person> + <name> + <given>Warren</given> + <common>Block</common> + </name> + <email>wblock@FreeBSD.org</email> + </person> + </contact> + + <links> + <url href="https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/">&os; Documentation Project Primer</url> + <url href="https://svnweb.freebsd.org/doc/head/share/mk/doc.docbook.mk?r1=50233&r2=50232&pathrev=50233">Get Version Information from Subversion Metadata</url> + </links> + + <body> + <p>In retrospect, our <tt>$FreeBSD$</tt> strings in + source files are kind of weird, like a vestigial tail. The + version control system stores all of that information in + metadata. Yet here we are, not only allowing the version + control system to alter our source files on every commit, but + forcing it to do so.</p> + + <p>The reason for doing so is that the previous version control + system did it. Really.</p> + + <p>Version control strings are a headache for translators using + the new PO toolchain. It is an ever-changing string that offers + nothing to the translation, yet can cause conflicts with earlier + versions of itself.</p> + + <p>We also had complaints about how the Handbook was always months + out of date. It was not, of course... but looking at just the + version string in the main, rarely-changing book.xml file gave + that impression. We fixed that problem last year, so the build + system checks all the source files for the latest commit, but it + seems easier to not have to fix the problem at all.</p> + + <p>Of course, that was really only one aspect of an ongoing + problem. Our documentation build system was checking the + version string in the source file, not the metadata. In 1973, + metadata, like cars not composed chiefly of rust, had not yet + been invented. I modified the build system to extract the + information from the metadata (and noted, with some surprise, + that this is a task at which Git is much better than + Subversion).</p> + + <p>The next step was to remove the + <tt>$FreeBSD$</tt> strings from the source files + and remove the <tt>FreeBSD=%H</tt> property that forces + Subversion, against its better judgement, to substitute text in + the actual contents of the file. The version information is not + lost. It lives in the metadata, so retrieving it is as simple + as <tt>svn info</tt> — it does not need to be in the + source at all. However, as with anything that touches code or + processes which have not been touched in living memory, there + was some debate over this. At that point, I offered to remove + the version strings from the &os; Documentation Project Primer + book as a test.</p> + + <p>The change allowed the <tt>zh_TW</tt> translation team to turn + off the <tt>FreeBSD=%H</tt> property on their translation and + continue their work without fighting with the version strings. + Rendered versions of the book still display the name of the last + committer and the date and revision number of the last commit, + but all of that information comes from metadata. As such, it is + also more likely to be correct.</p> + + <p>Since the change, there have not been any complaints, at least + not to me. In fairness, the removal of version strings from the + FDP Primer alone is a small change in a tiny corner of the + project. Looking at it another way, it might be that some + things that seem to be necessary are more about comfort in + familiarity than actual utility.</p> + + <p>At present, this is strictly a change to the documentation + build toolchain and a single documentation book. However, there + do not appear to be any reasons it could not be extended to the + rest of the documents. It might even serve as tiny test of + whether the expansion of <tt>$FreeBSD$</tt> tags + is needed throughout the rest of the &os; tree.</p> + </body> + </project> </report>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201707292331.v6TNVBRs017712>