6

The l3bootstrap's documentation says \GetIdInfo extracts all information from a SVN field. But I have no idea where this field comes from. So I'd like to know how \GetIdInfo does work and if it is possible to make it work with another DVCS, such as Git (possibly with gitinfo2 package).

Edit: I'm starting to play with LaTeX3 for a class I have to write and I'd like to have best practices as soon as possible. So I had a look at the LaTeX3 .dtx files and see, e.g. in l3doc.dtx, something like:

\RequirePackage{expl3,xparse,calc}
\GetIdInfo$Id: l3doc.dtx 5353 2014-08-23 01:23:51Z bruno $
          {L3 Experimental documentation class}
[...]
\ProvidesFile{\ExplFileName.dtx}
  [\ExplFileDate\space v\ExplFileVersion\space\ExplFileDescription]
[...]
\ProvidesExplClass
  {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
[...]

I understand I can manually replace information between the two $s but, as \GetIdInfo is able to extracts all information from a SVN field, I guess this has been done automatically for l3doc.dtx. Hence my question.

  • 2
    Based on many auxiliar commands it starts reading the info with special delimiters like $#1 #2.#3 #4 #5 #6$ or $#1-#2-#3$. Perhaps you should post a more concrete code and what do you exactly want to do with it. – Manuel Sep 17 '14 at 14:51
  • I have edited my question. I hope it is more concrete now. – Denis Bitouzé Sep 17 '14 at 15:08
  • 1
    When the distribution is pulled from the SVN repository, the fields are supplied and made part of the text files, so \GetIdInfo can do its work. It doesn't look in a SVN repository, which TeX can't do to begin with. How the SVN information is supplied and written depends on the scripts used for pulling. – egreg Sep 17 '14 at 16:06
  • What is the tool that supplies the fields and make them part of the text files? Something à la gitinfo2? – Denis Bitouzé Sep 17 '14 at 16:10
  • 1
    SVN itself does the substitution, I believe. SVN is an entirely different paradigm for VCS, so it has a few quirks that it does not share with DVCS systems like git. To get \GetIdInfo: to work under git, you would need to write a post-commit or post-tag hook that would format the version info correctly. – Sean Allred Sep 17 '14 at 16:13
4

There are two parts to this: one technical, one more conceptual. I'll deal with the technical part first, then the bigger picture ideas.

At a technical level, \GetIdInfo is as you say in the question designed to extract information between two $ markers in a standard Subversion (SVN) Id block. That will looks something like

\GetIdInfo$Id: l3galley.dtx 5423 2014-09-15 10:48:14Z joseph $

So the question then is how the data gets there in the first place: more of a Subversion thing than a TeX one (see http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html for the full Subversion details). What happens is that for each file to have the Id block scans has to have the correct property set

svn ps svn:keywords Id <filename>

so in my example the file l3galley.dtx has this property set. With this active, a check-in to the version control system will scan the file looking for

$Id<stuff>$

and replace the <stuff> with the information about the current check-in (filename/revision/time/date/user). Thus a 'blank' Id block can be included initially with just $Id$.

The key point here is that the Id block is only updated because the various files involved are managed using Subversion and only because they are marked as such. Thus the data is added to the source files during the check-in process to the team server.

This brings us on to the concepts. For the team, a key requirement is that all files carry 'current' version data with them at all times. The idea here is that unlike a binary, it's relatively easy to take the LaTeX sources and extract the code for direct use, so users could in principle be using arbitrary versions of the code. Thus unless the 'live' version number needs to be in each source file so that its present in all files used in a compilation. (Note: this requirement pre-dates my involvement with the team, and so the factors behind it are best explained by others.)

The pretty 'tight' versioning requirement for the team is not one that necessarily applies to other LaTeX programmers. In addition, the idea of a Id block is pretty closely tied to 'classic' version control systems, in particular Subverion, which have a single global series of versions and a 'definitive' source. Distributed systems such as Git and Mercurial don't have this. Moreover, they don't really encourage the form of search-and-replace concept which Subversion uses for the Id block. I know that the people behind Git are really not keen on this, while for Mercurial there is an extension that does it but that itself is complex. (Any add-ons to emulate the Subversion Id concept are not active 'out of the box' so can easily be missed: I'd therefore not choose to go down this route.)

The net result of these considerations is that there is not really a strong reason for users outside of the team to use \GetIdInfo. It's notable that in the 'personal' code of individual team members \GetIdInfo is not necessarily used. For example, in my own code I use a more standard <major>.<minor><patch> version scheme with file dates altered by hand and set as part of the process of building uploads to CTAN. For example, in the current release of siunitx you'll find

\ProvidesExplPackage {siunitx} {2014/09/15} {2.6a}
  {A comprehensive (SI) units package}

rather than any \GetIdInfo line.

Note that while it is possible to grab version data from distributed version systems, the methods to do this in a LaTeX context tend to be focussed on including data in typeset output rather than into source files. As such, they are probably not appropriate to handling code releases.

  • 1
    Note on the SVN side that the stored files don't show the 'filled in' Id block unless you check them out. For example, if you look at the mirror of the SVN on GitHub (github.com/latex3/svn-mirror) there are no versions. – Joseph Wright Sep 17 '14 at 20:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.