os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add 2017Q2 entry on $FreeBSD$-string removal from wblock

Browse source
This commit is contained in:
Benjamin Kaduk 2017-07-29 23:31:11 +00:00
parent dcb6abdb4c
commit e93dd58b2c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=50608
1 changed files with 87 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

87
en_US.ISO8859-1/htdocs/news/status/report-2017-04-2017-06.xml
View file

@ -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&amp;r2=50232&amp;pathrev=50233">Get Version Information from Subversion Metadata</url>
</links>
<body>
<p>In retrospect, our <tt>&dollar;FreeBSD&dollar;</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>&dollar;FreeBSD&dollar;</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> &mdash; 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>&dollar;FreeBSD&dollar;</tt> tags
is needed throughout the rest of the &os; tree.</p>
</body>
</project>
</report>