svn commit: r50608 - head/en_US.ISO8859-1/htdocs/news/status

Sat Jul 29 23:31:12 UTC 2017

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 at 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>
