From owner-svn-doc-all@freebsd.org Sat Jul 29 23:31:12 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 3E3B7DCD808; Sat, 29 Jul 2017 23:31:12 +0000 (UTC) (envelope-from bjk@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 1ACE880690; Sat, 29 Jul 2017 23:31:12 +0000 (UTC) (envelope-from bjk@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v6TNVBIv017713; Sat, 29 Jul 2017 23:31:11 GMT (envelope-from bjk@FreeBSD.org) Received: (from bjk@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v6TNVBRs017712; Sat, 29 Jul 2017 23:31:11 GMT (envelope-from bjk@FreeBSD.org) Message-Id: <201707292331.v6TNVBRs017712@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bjk set sender to bjk@FreeBSD.org using -f From: Benjamin Kaduk Date: Sat, 29 Jul 2017 23:31:11 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: bjk X-SVN-Commit-Paths: head/en_US.ISO8859-1/htdocs/news/status X-SVN-Commit-Revision: 50608 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 29 Jul 2017 23:31:12 -0000 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 for details. + + + Doc Version Strings Improved by Their Absence + + + + + Warren + Block + + wblock@FreeBSD.org + + + + + &os; Documentation Project Primer + Get Version Information from Subversion Metadata + + + +

In retrospect, our $FreeBSD$ 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.

+ +

The reason for doing so is that the previous version control + system did it. Really.

+ +

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.

+ +

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.

+ +

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).

+ +

The next step was to remove the + $FreeBSD$ strings from the source files + and remove the FreeBSD=%H 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 svn info — 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.

+ +

The change allowed the zh_TW translation team to turn + off the FreeBSD=%H 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.

+ +

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.

+ +

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 $FreeBSD$ tags + is needed throughout the rest of the &os; tree.

+ +