svn commit: r50608 - head/en_US.ISO8859-1/htdocs/news/status
Benjamin Kaduk <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
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>[email protected]</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>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"