diff options
Diffstat (limited to 'support/vc')
-rw-r--r-- | support/vc/CHANGES | 80 | ||||
-rw-r--r-- | support/vc/LICENSE | 114 | ||||
-rw-r--r-- | support/vc/README | 51 | ||||
-rw-r--r-- | support/vc/bzr-unix/vc | 25 | ||||
-rw-r--r-- | support/vc/bzr-unix/vc-bzr.awk | 62 | ||||
-rw-r--r-- | support/vc/bzr-windows/vc-bzr.awk | 62 | ||||
-rw-r--r-- | support/vc/bzr-windows/vc.bat | 25 | ||||
-rw-r--r-- | support/vc/git-unix/vc | 43 | ||||
-rw-r--r-- | support/vc/git-unix/vc-git.awk | 81 | ||||
-rw-r--r-- | support/vc/git-windows/vc-git.awk | 81 | ||||
-rw-r--r-- | support/vc/git-windows/vc.bat | 24 | ||||
-rwxr-xr-x | support/vc/hg-unix/vc | 40 | ||||
-rw-r--r-- | support/vc/hg-unix/vc-hg.awk | 75 | ||||
-rw-r--r-- | support/vc/hg-windows/vc-hg.awk | 75 | ||||
-rw-r--r-- | support/vc/hg-windows/vc.bat | 25 | ||||
-rwxr-xr-x | support/vc/make-release.sh | 41 | ||||
-rw-r--r-- | support/vc/svn-unix/vc | 24 | ||||
-rw-r--r-- | support/vc/svn-unix/vc-svn.awk | 136 | ||||
-rw-r--r-- | support/vc/svn-windows/vc-svn.awk | 136 | ||||
-rw-r--r-- | support/vc/svn-windows/vc.bat | 24 | ||||
-rw-r--r-- | support/vc/vc-manual.pdf | bin | 0 -> 425782 bytes | |||
-rw-r--r-- | support/vc/vc-manual.tex | 702 |
22 files changed, 1926 insertions, 0 deletions
diff --git a/support/vc/CHANGES b/support/vc/CHANGES new file mode 100644 index 0000000000..3cc2358078 --- /dev/null +++ b/support/vc/CHANGES @@ -0,0 +1,80 @@ +v0.6 (2018-06-11) +---------------------- +Changes: +* Meta: + - New maintainer: Roland Hieber <rohieb+ctan@rohieb.name> + - Move code to GitHub: https://github.com/rohieb/ctan-support-vc +* Add support for Mercurial, thanks to ildar nizamov (@niya3 on GitHub) +* Git: parse the machine-readable output of `git status --porcelain` + - fixes the issue that local modifications were not detected in recent Git + versions +* Git: use committer date instead of author date for \VCDate, since author date + is not guaranteed to be monotonous +* Some code cleanup + + +v0.5 (2008-04-21) +---------------------- +Incompatible changes: +* Don't write sensitive information to vc.tex, by default (see appendix A). + - Bazaar: + \BZRBranchNick + - Subversion: + \SVNPath, \SVNName, \SVNUrl, \SVNNodeKind, \SVNRepositoryRoot + + +v0.42 (2008-04-17) +---------------------- +Changes: +* Small documentation update. + + +v0.41 (2008-04-11) +---------------------- +Changes: +* Small documentation update. + + +v0.4 (2008-04-10) +---------------------- +Incompatible changes: +* Search for local modifications only at request + (relevant to macro \VCRevisionMod, see appendix B). + +Changes: +* Again improved locale handling. +* Improved compatibility for Subversion within Msys shell. +* Improved documentation: + + +v0.3 (2008-03-20) +---------------------- +New: +* Added support for Bazaar. +* The vc bundle is now Public Domain. + +Changes: +* Fixed line endings in Unix scripts (solving several issues). +* Fixed handling of variable LANG in shell scripts. +* Improved documentation: + - Added some more "Questions and answers". + + +v0.21 (2008-03-10) +---------------------- +* Incompatible change: + - Removed macros \VCDate, \VCLongDate, \VCDateTeX. + - Introduced macros \VCDateRAW, \VCDateISO, \VCDateTEX. +* Improved documentation: + - Added section "Questions and answers". + + +v0.2 (2008-03-06) +---------------------- +* Added documentation. +* First upload to CTAN. + + +v0.1alpha (2008-03-04) +---------------------- +* First public announcement on comp.text.tex. diff --git a/support/vc/LICENSE b/support/vc/LICENSE new file mode 100644 index 0000000000..35a1ec7843 --- /dev/null +++ b/support/vc/LICENSE @@ -0,0 +1,114 @@ +CC0 1.0 Universal +================= + +CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL +SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT +RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. +CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE +INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES +RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED +HEREUNDER. + +Statement of Purpose + +The laws of most jurisdictions throughout the world automatically confer +exclusive Copyright and Related Rights (defined below) upon the creator and +subsequent owner(s) (each and all, an "owner") of an original work of +authorship and/or a database (each, a "Work"). + +Certain owners wish to permanently relinquish those rights to a Work for the +purpose of contributing to a commons of creative, cultural and scientific works +("Commons") that the public can reliably and without fear of later claims of +infringement build upon, modify, incorporate in other works, reuse and +redistribute as freely as possible in any form whatsoever and for any purposes, +including without limitation commercial purposes. These owners may contribute +to the Commons to promote the ideal of a free culture and the further +production of creative, cultural and scientific works, or to gain reputation or +greater distribution for their Work in part through the use and efforts of +others. + +For these and/or other purposes and motivations, and without any expectation of +additional consideration or compensation, the person associating CC0 with a +Work (the "Affirmer"), to the extent that he or she is an owner of Copyright +and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and +publicly distribute the Work under its terms, with knowledge of his or her +Copyright and Related Rights in the Work and the meaning and intended legal +effect of CC0 on those rights. + +1. Copyright and Related Rights. A Work made available under CC0 may be +protected by copyright and related or neighboring rights ("Copyright and Related +Rights"). Copyright and Related Rights include, but are not limited to, the +following: + +i. the right to reproduce, adapt, distribute, perform, display, + communicate, and translate a Work; +ii. moral rights retained by the original author(s) and/or performer(s); +iii. publicity and privacy rights pertaining to a person's image or + likeness depicted in a Work; +iv. rights protecting against unfair competition in regards to a Work, + subject to the limitations in paragraph 4(a), below; +v. rights protecting the extraction, dissemination, use and reuse of data + in a Work; +vi. database rights (such as those arising under Directive 96/9/EC of the + European Parliament and of the Council of 11 March 1996 on the legal + protection of databases, and under any national implementation + thereof, including any amended or successor version of such + directive); and +vii. other similar, equivalent or corresponding rights throughout the world + based on applicable law or treaty, and any national implementations + thereof. + +2. Waiver. To the greatest extent permitted by, but not in contravention of, +applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and +unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and +Related Rights and associated claims and causes of action, whether now known or +unknown (including existing as well as future claims and causes of action), in +the Work (i) in all territories worldwide, (ii) for the maximum duration +provided by applicable law or treaty (including future time extensions), (iii) +in any current or future medium and for any number of copies, and (iv) for any +purpose whatsoever, including without limitation commercial, advertising or +promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit +of each member of the public at large and to the detriment of Affirmer's heirs +and successors, fully intending that such Waiver shall not be subject to +revocation, rescission, cancellation, termination, or any other legal or +equitable action to disrupt the quiet enjoyment of the Work by the public as +contemplated by Affirmer's express Statement of Purpose. + +3. Public License Fallback. Should any part of the Waiver for any reason be +judged legally invalid or ineffective under applicable law, then the Waiver +shall be preserved to the maximum extent permitted taking into account +Affirmer's express Statement of Purpose. In addition, to the extent the Waiver +is so judged Affirmer hereby grants to each affected person a royalty-free, non +transferable, non sublicensable, non exclusive, irrevocable and unconditional +license to exercise Affirmer's Copyright and Related Rights in the Work (i) in +all territories worldwide, (ii) for the maximum duration provided by applicable +law or treaty (including future time extensions), (iii) in any current or future +medium and for any number of copies, and (iv) for any purpose whatsoever, +including without limitation commercial, advertising or promotional purposes +(the "License"). The License shall be deemed effective as of the date CC0 was +applied by Affirmer to the Work. Should any part of the License for any reason +be judged legally invalid or ineffective under applicable law, such partial +invalidity or ineffectiveness shall not invalidate the remainder of the License, +and in such case Affirmer hereby affirms that he or she will not (i) exercise +any of his or her remaining Copyright and Related Rights in the Work or (ii) +assert any associated claims and causes of action with respect to the Work, in +either case contrary to Affirmer's express Statement of Purpose. + +4. Limitations and Disclaimers. + +a. No trademark or patent rights held by Affirmer are waived, abandoned, + surrendered, licensed or otherwise affected by this document. +b. Affirmer offers the Work as-is and makes no representations or warranties of + any kind concerning the Work, express, implied, statutory or otherwise, + including without limitation warranties of title, merchantability, fitness + for a particular purpose, non infringement, or the absence of latent or + other defects, accuracy, or the present or absence of errors, whether or not + discoverable, all to the greatest extent permissible under applicable law. +c. Affirmer disclaims responsibility for clearing rights of other persons that + may apply to the Work or any use thereof, including without limitation any + person's Copyright and Related Rights in the Work. Further, Affirmer + disclaims responsibility for obtaining any necessary consents, permissions + or other rights required for any use of the Work. +d. Affirmer understands and acknowledges that Creative Commons is not a party + to this document and has no duty or obligation with respect to this CC0 or + use of the Work. diff --git a/support/vc/README b/support/vc/README new file mode 100644 index 0000000000..9139a7e396 --- /dev/null +++ b/support/vc/README @@ -0,0 +1,51 @@ +Name: The vc bundle +Version: v0.6 +Authors: Roland Hieber <rohieb+ctan@rohieb.name>, + Stephan Hennig <stephanhennig@arcor.de> +Last modified: 2018-06-11 +License: CC0 1.0 (Public Domain Dedication), see ./LICENSE, + or <URL:http://creativecommons.org/publicdomain/zero/1.0/> + + +The vc bundle +----------------------------------- +This is a script based approach to version control for TeX +documents. It works more reliably than keyword substitution +based approaches, since it tracks all files in a working +copy, not only .tex files. + +The vc bundle works with LaTeX and plain TeX. Currently, +Bazaar, Git, Mercurial and Subversion are supported. + + +What's special about the vc bundle? +----------------------------------- +* Common version control packages for LaTeX use keyword + substitution to access revision information. That + approach doesn't work reliably in the presence of + non-.tex files, e.g., graphics or graphic sources that + are processed by an external tool. +* The author is unaware of any alternative version control + packages for plain TeX. +* The author is unaware of any alternative LaTeX version + control packages that support Bazaar or Git. + + +Getting the software +----------------------------------- +The latest version of the vc bundle can be found at +CTAN:support/vc. + +<URL:http://www.ctan.org/get/support/vc.zip> + +The source repository can be found on GitHub. + +<URL:https://github.com/rohieb/ctan-support-vc> + + +Installation and Usage +----------------------------------- +Please see the manual in vc-manual.pdf. + +Happy TeXing! +Stephan Hennig diff --git a/support/vc/bzr-unix/vc b/support/vc/bzr-unix/vc new file mode 100644 index 0000000000..e9c3f47a8f --- /dev/null +++ b/support/vc/bzr-unix/vc @@ -0,0 +1,25 @@ +#!/bin/sh +# This is file 'vc' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +# Parse command line options. +full=0 +mod=0 +while [ -n "$(echo $1 | grep '-')" ]; do + case $1 in + -f ) full=1 ;; + -m ) mod=1 ;; + * ) echo 'usage: vc [-f] [-m]' + exit 1 + esac + shift +done +# English locale. +LC_ALL=C +if [ "$mod" = 1 ] +then + bzr version-info --check-clean|gawk -v full=$full -f vc-bzr.awk > vc.tex +else + bzr version-info |gawk -v full=$full -f vc-bzr.awk > vc.tex +fi diff --git a/support/vc/bzr-unix/vc-bzr.awk b/support/vc/bzr-unix/vc-bzr.awk new file mode 100644 index 0000000000..cec1628f4b --- /dev/null +++ b/support/vc/bzr-unix/vc-bzr.awk @@ -0,0 +1,62 @@ +# This is file 'vc-bzr.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. +BEGIN { +### Assume clean working copy. + Clean = "True" +} +/^revision-id:/ { RevisionId = substr($0, 2+match($0, ":")) } +/^date:/ { Date = substr($0, 2+match($0, ":")) } +/^build-date:/ { BuildDate = substr($0, 2+match($0, ":")) } +/^revno:/ { RevNo = substr($0, 2+match($0, ":")) } +/^branch-nick:/ { BranchNick = substr($0, 2+match($0, ":")) } +/^clean:/ { Clean = substr($0, 2+match($0, ":")) } +END { +### Extract relevant information from variables. + elements = split(RevisionId, elem, "-") + Author = elem[1] + for (i=2; i<elements-2; i++) { + Author = Author "-" elem[i] + } + LongDate = substr(Date, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + if (Clean=="True") { + modified = 0 + } else { + modified = 1 + } +### Write file identification to vc.tex. + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" +### Write Bazaar specific macros. + print "%%% Define Bazaar specific macros." + print "\\gdef\\BZRRevisionId{" RevisionId "}%" + print "\\gdef\\BZRDate{" Date "}%" + print "\\gdef\\BZRBuildDate{" BuildDate "}%" + print "\\gdef\\BZRRevNo{" RevNo "}%" + if (full==1) { + print "\\gdef\\BZRBranchNick{" BranchNick "}%" + } +### Write generic version control macros. + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\BZRRevNo}%" + print "\\gdef\\VCAuthor{" Author "}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" +### Is working copy modified? + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } +} diff --git a/support/vc/bzr-windows/vc-bzr.awk b/support/vc/bzr-windows/vc-bzr.awk new file mode 100644 index 0000000000..cec1628f4b --- /dev/null +++ b/support/vc/bzr-windows/vc-bzr.awk @@ -0,0 +1,62 @@ +# This is file 'vc-bzr.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. +BEGIN { +### Assume clean working copy. + Clean = "True" +} +/^revision-id:/ { RevisionId = substr($0, 2+match($0, ":")) } +/^date:/ { Date = substr($0, 2+match($0, ":")) } +/^build-date:/ { BuildDate = substr($0, 2+match($0, ":")) } +/^revno:/ { RevNo = substr($0, 2+match($0, ":")) } +/^branch-nick:/ { BranchNick = substr($0, 2+match($0, ":")) } +/^clean:/ { Clean = substr($0, 2+match($0, ":")) } +END { +### Extract relevant information from variables. + elements = split(RevisionId, elem, "-") + Author = elem[1] + for (i=2; i<elements-2; i++) { + Author = Author "-" elem[i] + } + LongDate = substr(Date, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + if (Clean=="True") { + modified = 0 + } else { + modified = 1 + } +### Write file identification to vc.tex. + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" +### Write Bazaar specific macros. + print "%%% Define Bazaar specific macros." + print "\\gdef\\BZRRevisionId{" RevisionId "}%" + print "\\gdef\\BZRDate{" Date "}%" + print "\\gdef\\BZRBuildDate{" BuildDate "}%" + print "\\gdef\\BZRRevNo{" RevNo "}%" + if (full==1) { + print "\\gdef\\BZRBranchNick{" BranchNick "}%" + } +### Write generic version control macros. + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\BZRRevNo}%" + print "\\gdef\\VCAuthor{" Author "}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" +### Is working copy modified? + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } +} diff --git a/support/vc/bzr-windows/vc.bat b/support/vc/bzr-windows/vc.bat new file mode 100644 index 0000000000..9ea3cbbebf --- /dev/null +++ b/support/vc/bzr-windows/vc.bat @@ -0,0 +1,25 @@ +@echo off +REM This is file 'vc.bat' from the vc bundle for TeX. +REM The original file can be found at CTAN:support/vc. +REM This file is Public Domain. + +setlocal +REM Parse command line options. +set full=0 +set mod=0 +:loopParams +if "%1" NEQ "" ( + if "%1"=="-f" (set full=1) else if "%1"=="-m" (set mod=1) else ( + echo usage: vc [-f] [-m] + exit /b 1 + ) + shift + goto loopParams +) +REM English locale. +set LC_ALL=C +if "%mod%"=="1" ( + bzr version-info --check-clean|gawk -v full=%full% -f vc-bzr.awk > vc.tex +) else ( + bzr version-info |gawk -v full=%full% -f vc-bzr.awk > vc.tex +) diff --git a/support/vc/git-unix/vc b/support/vc/git-unix/vc new file mode 100644 index 0000000000..63c737e4e3 --- /dev/null +++ b/support/vc/git-unix/vc @@ -0,0 +1,43 @@ +#!/bin/sh +# This is file 'vc' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +# Parse command line options +full=0 +mod=0 +while [ -n "$(echo $1 | grep '-')" ]; do + case $1 in + -f) full=1 ;; + -m) mod=1 ;; + * ) + echo 'usage: vc [-f] [-m]' + exit 1 + ;; + esac + shift +done + +# Query all info from git log +logformat="" +logformat="${logformat}Hash: %H%n" +logformat="${logformat}AbrHash: %h%n" +logformat="${logformat}ParentHashes: %P%n" +logformat="${logformat}AbrParentHashes: %p%n" +logformat="${logformat}AuthorName: %an%n" +logformat="${logformat}AuthorEmail: %ae%n" +logformat="${logformat}AuthorDate: %ai%n" +logformat="${logformat}CommitterName: %cn%n" +logformat="${logformat}CommitterEmail: %ce%n" +logformat="${logformat}CommitterDate: %ci%n" +LC_ALL=C +git --no-pager log -1 HEAD --pretty=format:"$logformat" \ + | gawk -v script=log -v full=$full -f vc-git.awk \ + > vc.tex + +# Query modification status of the working copy +if [ "$mod" = 1 ]; then + git status --porcelain=v1 \ + | gawk -v script=status -f vc-git.awk \ + >> vc.tex +fi diff --git a/support/vc/git-unix/vc-git.awk b/support/vc/git-unix/vc-git.awk new file mode 100644 index 0000000000..ec85071263 --- /dev/null +++ b/support/vc/git-unix/vc-git.awk @@ -0,0 +1,81 @@ +# This is file 'vc-git.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +BEGIN { + modified = 0 +} + +### Process output of "git log" +script == "log" && /^Hash:/ { Hash = substr($0, 2+match($0, ":")) } +script == "log" && /^AbrHash:/ { AbrHash = substr($0, 2+match($0, ":")) } +script == "log" && /^ParentHashes:/ { ParentHashes = substr($0, 2+match($0, ":")) } +script == "log" && /^AbrParentHashes:/ { AbrParentHashes = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorName:/ { AuthorName = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorEmail:/ { AuthorEmail = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorDate:/ { AuthorDate = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterName:/ { CommitterName = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterEmail:/ { CommitterEmail = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterDate:/ { CommitterDate = substr($0, 2+match($0, ":")) } + +### Process output of "git status" +### Changed index? +script == "status" && /^[mMADRCU] / { modified = 1 } +### Unstaged modifications? +script == "status" && /^ [mMADRCU]/ { modified = 1 } +### Unresolved merge conflicts? +script == "status" && /^[mMADRCU][mMADRCU]/ { modified = 1 } + +END { + ### Process output of "git log" + if (script == "log") { + ### Format dates + LongDate = substr(CommitterDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" + + print "%%% Define Git specific macros." + print "\\gdef\\GITHash{" Hash "}%" + print "\\gdef\\GITAbrHash{" AbrHash "}%" + print "\\gdef\\GITParentHashes{" ParentHashes "}%" + print "\\gdef\\GITAbrParentHashes{" AbrParentHashes "}%" + print "\\gdef\\GITAuthorName{" AuthorName "}%" + print "\\gdef\\GITAuthorEmail{" AuthorEmail "}%" + print "\\gdef\\GITAuthorDate{" AuthorDate "}%" + print "\\gdef\\GITCommitterName{" CommitterName "}%" + print "\\gdef\\GITCommitterEmail{" CommitterEmail "}%" + print "\\gdef\\GITCommitterDate{" CommitterDate "}%" + + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\GITAbrHash}%" + print "\\gdef\\VCAuthor{\\GITAuthorName}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } + + ### Process output of "git status" + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified == 0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } + +} diff --git a/support/vc/git-windows/vc-git.awk b/support/vc/git-windows/vc-git.awk new file mode 100644 index 0000000000..ec85071263 --- /dev/null +++ b/support/vc/git-windows/vc-git.awk @@ -0,0 +1,81 @@ +# This is file 'vc-git.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +BEGIN { + modified = 0 +} + +### Process output of "git log" +script == "log" && /^Hash:/ { Hash = substr($0, 2+match($0, ":")) } +script == "log" && /^AbrHash:/ { AbrHash = substr($0, 2+match($0, ":")) } +script == "log" && /^ParentHashes:/ { ParentHashes = substr($0, 2+match($0, ":")) } +script == "log" && /^AbrParentHashes:/ { AbrParentHashes = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorName:/ { AuthorName = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorEmail:/ { AuthorEmail = substr($0, 2+match($0, ":")) } +script == "log" && /^AuthorDate:/ { AuthorDate = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterName:/ { CommitterName = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterEmail:/ { CommitterEmail = substr($0, 2+match($0, ":")) } +script == "log" && /^CommitterDate:/ { CommitterDate = substr($0, 2+match($0, ":")) } + +### Process output of "git status" +### Changed index? +script == "status" && /^[mMADRCU] / { modified = 1 } +### Unstaged modifications? +script == "status" && /^ [mMADRCU]/ { modified = 1 } +### Unresolved merge conflicts? +script == "status" && /^[mMADRCU][mMADRCU]/ { modified = 1 } + +END { + ### Process output of "git log" + if (script == "log") { + ### Format dates + LongDate = substr(CommitterDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" + + print "%%% Define Git specific macros." + print "\\gdef\\GITHash{" Hash "}%" + print "\\gdef\\GITAbrHash{" AbrHash "}%" + print "\\gdef\\GITParentHashes{" ParentHashes "}%" + print "\\gdef\\GITAbrParentHashes{" AbrParentHashes "}%" + print "\\gdef\\GITAuthorName{" AuthorName "}%" + print "\\gdef\\GITAuthorEmail{" AuthorEmail "}%" + print "\\gdef\\GITAuthorDate{" AuthorDate "}%" + print "\\gdef\\GITCommitterName{" CommitterName "}%" + print "\\gdef\\GITCommitterEmail{" CommitterEmail "}%" + print "\\gdef\\GITCommitterDate{" CommitterDate "}%" + + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\GITAbrHash}%" + print "\\gdef\\VCAuthor{\\GITAuthorName}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } + + ### Process output of "git status" + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified == 0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } + +} diff --git a/support/vc/git-windows/vc.bat b/support/vc/git-windows/vc.bat new file mode 100644 index 0000000000..ede0d40156 --- /dev/null +++ b/support/vc/git-windows/vc.bat @@ -0,0 +1,24 @@ +@echo off +REM This is file 'vc.bat' from the vc bundle for TeX. +REM The original file can be found at CTAN:support/vc. +REM This file is Public Domain. + +setlocal +REM Parse command line options. +set full=0 +set mod=0 +:loopParams +if "%1" NEQ "" ( + if "%1"=="-f" (set full=1) else if "%1"=="-m" (set mod=1) else ( + echo usage: vc [-f] [-m] + exit /b 1 + ) + shift + goto loopParams +) +REM English locale. +set LC_ALL=C +git --no-pager log -1 HEAD --pretty=format:"Hash: %H%nAbr. Hash: %h%nParent Hashes: %P%nAbr. Parent Hashes: %p%nAuthor Name: %an%nAuthor Email: %ae%nAuthor Date: %ai%nCommitter Name: %cn%nCommitter Email: %ce%nCommitter Date: %ci%n" |gawk -v script=log -v full=%full% -f vc-git.awk > vc.tex +if "%mod%"=="1" ( + git status --porcelain=v1 |gawk -v script=status -f vc-git.awk >> vc.tex +) diff --git a/support/vc/hg-unix/vc b/support/vc/hg-unix/vc new file mode 100755 index 0000000000..9916f854bb --- /dev/null +++ b/support/vc/hg-unix/vc @@ -0,0 +1,40 @@ +#!/bin/sh +# This is file 'vc' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +# Parse command line options. +mod=0 +while [ -n "$(echo $1 | grep '-')" ]; do + case $1 in + -m ) mod=1 ;; + * ) + echo 'usage: vc [-m]' + exit 1 + ;; + esac + shift +done + +logformat="" +logformat="${logformat}Hash: {node}" +logformat="${logformat}Abr. Hash: {node|short}" +logformat="${logformat}Branch: {branch}" +logformat="${logformat}Parent1 Hash: {p1node}" +logformat="${logformat}Parent2 Hash: {p2node}" +logformat="${logformat}Abr. Parent1 Hash: {p1node|short}" +logformat="${logformat}Abr. Parent2 Hash: {p2node|short}" +logformat="${logformat}Author Name: {author|user}" +logformat="${logformat}Author Email: {author|email}" +logformat="${logformat}Author Date: {date|isodatesec}" + +LC_ALL=C +hg log --pager=off -r . --template "${logformat}" \ + | gawk -v script=log -f vc-hg.awk \ + > vc.tex + +if [ "$mod" = 1 ]; then + hg status --pager=off \ + | gawk -v script=status -f vc-hg.awk \ + >> vc.tex +fi diff --git a/support/vc/hg-unix/vc-hg.awk b/support/vc/hg-unix/vc-hg.awk new file mode 100644 index 0000000000..077d2ed90d --- /dev/null +++ b/support/vc/hg-unix/vc-hg.awk @@ -0,0 +1,75 @@ +# This is file 'vc-hg.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +BEGIN { + modified = 0 +} + +### Process output of "hg log" +script=="log" && /^Hash:/ { Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Hash:/ { AbrHash = substr($0, 2+match($0, ":")) } +script=="log" && /^Branch:/ { Branch = substr($0, 2+match($0, ":")) } +script=="log" && /^Parent1 Hash:/ { Parent1Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Parent2 Hash:/ { Parent2Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Parent1 Hash:/ { AbrParent1Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Parent2 Hash:/ { AbrParent2Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Name:/ { AuthorName = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Email:/ { AuthorEmail = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Date:/ { AuthorDate = substr($0, 2+match($0, ":")) } + +### Process output of "hg status" +script=="status" && /^M / { modified = 1 } + +END { + ### Process output of "hg log" + if (script=="log") { + ### Format dates + LongDate = substr(AuthorDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" + + print "%%% Define HG specific macros." + print "\\gdef\\HGHash{" Hash "}%" + print "\\gdef\\HGAbrHash{" AbrHash "}%" + print "\\gdef\\HGBranch{" Branch "}%" + print "\\gdef\\HGFirstParentHash{" Parent1Hash "}%" + print "\\gdef\\HGSecondParentHash{" Parent2Hash "}%" + print "\\gdef\\HGAbrFirstParentHash{" AbrParent1Hash "}%" + print "\\gdef\\HGAbrSecondParentHash{" AbrParent2Hash "}%" + print "\\gdef\\HGAuthorName{" AuthorName "}%" + print "\\gdef\\HGAuthorEmail{" AuthorEmail "}%" + print "\\gdef\\HGAuthorDate{" AuthorDate "}%" + + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\HGAbrHash}%" + print "\\gdef\\VCAuthor{\\HGAuthorName}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } + + ### Process output of "hg status" + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } +} diff --git a/support/vc/hg-windows/vc-hg.awk b/support/vc/hg-windows/vc-hg.awk new file mode 100644 index 0000000000..077d2ed90d --- /dev/null +++ b/support/vc/hg-windows/vc-hg.awk @@ -0,0 +1,75 @@ +# This is file 'vc-hg.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +BEGIN { + modified = 0 +} + +### Process output of "hg log" +script=="log" && /^Hash:/ { Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Hash:/ { AbrHash = substr($0, 2+match($0, ":")) } +script=="log" && /^Branch:/ { Branch = substr($0, 2+match($0, ":")) } +script=="log" && /^Parent1 Hash:/ { Parent1Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Parent2 Hash:/ { Parent2Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Parent1 Hash:/ { AbrParent1Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Abr. Parent2 Hash:/ { AbrParent2Hash = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Name:/ { AuthorName = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Email:/ { AuthorEmail = substr($0, 2+match($0, ":")) } +script=="log" && /^Author Date:/ { AuthorDate = substr($0, 2+match($0, ":")) } + +### Process output of "hg status" +script=="status" && /^M / { modified = 1 } + +END { + ### Process output of "hg log" + if (script=="log") { + ### Format dates + LongDate = substr(AuthorDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) + + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" + + print "%%% Define HG specific macros." + print "\\gdef\\HGHash{" Hash "}%" + print "\\gdef\\HGAbrHash{" AbrHash "}%" + print "\\gdef\\HGBranch{" Branch "}%" + print "\\gdef\\HGFirstParentHash{" Parent1Hash "}%" + print "\\gdef\\HGSecondParentHash{" Parent2Hash "}%" + print "\\gdef\\HGAbrFirstParentHash{" AbrParent1Hash "}%" + print "\\gdef\\HGAbrSecondParentHash{" AbrParent2Hash "}%" + print "\\gdef\\HGAuthorName{" AuthorName "}%" + print "\\gdef\\HGAuthorEmail{" AuthorEmail "}%" + print "\\gdef\\HGAuthorDate{" AuthorDate "}%" + + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\HGAbrHash}%" + print "\\gdef\\VCAuthor{\\HGAuthorName}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } + + ### Process output of "hg status" + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } +} diff --git a/support/vc/hg-windows/vc.bat b/support/vc/hg-windows/vc.bat new file mode 100644 index 0000000000..affb891d25 --- /dev/null +++ b/support/vc/hg-windows/vc.bat @@ -0,0 +1,25 @@ +@echo off +REM This is file 'vc.bat' from the vc bundle for TeX. +REM The original file can be found at CTAN:support/vc. +REM This file is Public Domain. + +setlocal +REM Parse command line options. +set mod=0 +:loopParams +if "%1" NEQ "" ( + if "%1"=="-m" (set mod=1) else ( + echo usage: vc [-m] + exit /b 1 + ) + shift + goto loopParams +) +REM English locale. +set LC_ALL=C + +hg log --pager=off -r . --template "Hash: {node}\nAbr. Hash: {node|short}\nBranch: {branch}\nParent1 Hash: {p1node}\nParent2 Hash: {p2node}\nAbr. Parent1 Hash: {p1node|short}\nAbr. Parent2 Hash: {p2node|short}\nAuthor Name: {author|user}\nAuthor Email: {author|email}\nAuthor Date: {date|isodatesec}" | gawk -v script=log -f vc-hg.awk > vc.tex + +if "%mod%"=="1" ( + hg status --pager=off | gawk -v script=status -f vc-hg.awk >> vc.tex +) diff --git a/support/vc/make-release.sh b/support/vc/make-release.sh new file mode 100755 index 0000000000..eb85c4bded --- /dev/null +++ b/support/vc/make-release.sh @@ -0,0 +1,41 @@ +#!/bin/sh -e +if [ -z "$1" ]; then + echo "Usage: $0 <version>" + exit +fi + +version=$1 +date=`date +%Y-%m-%d` + +sed -i 's/^\(Version:\).*$/\1 v'"$version"'/' README +sed -i 's/^\(Last modified:\).*$/\1 '"$date"'/' README +sed -i 's/^\(\\newcommand\*{\\pkgversion}\).*$/\1{v'"$version"'}/' vc-manual.tex + +tmpfile=`mktemp` +( + echo "v$version ($date)" + echo "----------------------" + echo "* TODO: Describe the changes here." + echo + echo + cat CHANGES +) > $tmpfile +mv $tmpfile CHANGES +sensible-editor CHANGES + +git add CHANGES README vc-manual.tex +git commit -sm "release v$version" + +cd git-unix/ +./vc -m +mv vc.tex .. +cd .. + +pdflatex vc-manual.tex +pdflatex vc-manual.tex + +git add vc-manual.pdf +git commit -sm "update manual for version $version" +git tag -sm "release v$version" v$version + +git archive -v -o vc-v$version.zip --prefix=vc/ v$version diff --git a/support/vc/svn-unix/vc b/support/vc/svn-unix/vc new file mode 100644 index 0000000000..5d447eb283 --- /dev/null +++ b/support/vc/svn-unix/vc @@ -0,0 +1,24 @@ +#!/bin/sh +# This is file 'vc' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. + +# Parse command line options. +full=0 +mod=0 +while [ -n "$(echo $1 | grep '-')" ]; do + case $1 in + -f ) full=1 ;; + -m ) mod=1 ;; + * ) echo 'usage: vc [-f] [-m]' + exit 1 + esac + shift +done +# English locale. +LC_ALL=C +svn info -R . |gawk -v script=info -v full=$full -f vc-svn.awk > vc.tex +if [ "$mod" = 1 ] +then + svn status |gawk -v script=status -f vc-svn.awk >> vc.tex +fi diff --git a/support/vc/svn-unix/vc-svn.awk b/support/vc/svn-unix/vc-svn.awk new file mode 100644 index 0000000000..37179028a2 --- /dev/null +++ b/support/vc/svn-unix/vc-svn.awk @@ -0,0 +1,136 @@ +# This is file 'vc-svn.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. +BEGIN { + +### Process output of "svn info". + if (script=="info") { + MaxRevision = 0 + } + +### Process output of "svn status". + if (script=="status") { + modified = 0 + } + +} + + + +### Process output of "svn info". +### Save all lines of the current record in a corresponding variable. +script=="info" && /^Path:/ { RecPath = $0; next } +script=="info" && /^Name:/ { RecName = $0; next } +script=="info" && /^URL:/ { RecUrl = $0; next } +script=="info" && /^Repository Root:/ { RecRepositoryRoot = $0; next } +script=="info" && /^Repository UUID:/ { RecRepositoryUuid = $0; next } +script=="info" && /^Revision:/ { RecRevision = $2; next } +script=="info" && /^Node Kind:/ { RecNodeKind = $0; next } +script=="info" && /^Last Changed Author:/ { RecLastChangedAuthor = $0; next } +script=="info" && /^Last Changed Rev:/ { RecLastChangedRevision = $0; next } +script=="info" && /^Last Changed Date:/ { RecLastChangedDate = $0; next } +script=="info" && /^[\r]*$/ { +### If revision number of the new record is higher, +### save all lines from the new record. + if (RecRevision > MaxRevision) { + MaxPath = RecPath + MaxName = RecName + MaxUrl = RecUrl + MaxRepositoryRoot = RecRepositoryRoot + MaxRepositoryUuid = RecRepositoryUuid + MaxRevision = RecRevision + MaxNodeKind = RecNodeKind + MaxLastChangedAuthor = RecLastChangedAuthor + MaxLastChangedRev = RecLastChangedRevision + MaxLastChangedDate = RecLastChangedDate + } +} + +### Process output of "svn status". +### File with local modifications? +script=="status" && /^[^ ?]/ { modified = 1 } +### File with property modifications? +script=="status" && /^.[^ ]/ { modified = 2 } + + + +END { + +### Process output of "svn info". + if (script=="info") { +### Remove possible Windows line endings (e.g., for Msys). + gsub("\r$", "", MaxPath) + gsub("\r$", "", MaxName) + gsub("\r$", "", MaxUrl) + gsub("\r$", "", MaxRepositoryRoot) + gsub("\r$", "", MaxRepositoryUuid) + gsub("\r$", "", MaxRevision) + gsub("\r$", "", MaxNodeKind) + gsub("\r$", "", MaxLastChangedAuthor) + gsub("\r$", "", MaxLastChangedRev) + gsub("\r$", "", MaxLastChangedDate) +### Escape % characters for TeX compatibility. + gsub("%", "\\%", MaxUrl) + gsub("%", "\\%", MaxRepositoryRoot) +### Extract relevant information from variables. + Path = substr(MaxPath, 2+match(MaxPath, ":")) + Name = substr(MaxName, 2+match(MaxName, ":")) + Url = substr(MaxUrl, 2+match(MaxUrl, ":")) + RepositoryRoot = substr(MaxRepositoryRoot, 2+match(MaxRepositoryRoot, ":")) + RepositoryUuid = substr(MaxRepositoryUuid, 2+match(MaxRepositoryUuid, ":")) + Revision = MaxRevision + NodeKind = substr(MaxNodeKind, 2+match(MaxNodeKind, ":")) + LastChangedAuthor = substr(MaxLastChangedAuthor, 2+match(MaxLastChangedAuthor, ":")) + LastChangedRev = substr(MaxLastChangedRev, 2+match(MaxLastChangedRev, ":")) + LastChangedDate = substr(MaxLastChangedDate, 2+match(MaxLastChangedDate, ":")) + LongDate = substr(LastChangedDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) +### Write file identification to vc.tex. + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" +### Write Subversion specific macros. + print "%%% Define Subversion specific macros." + print "\\gdef\\SVNRevision{" Revision "}%" + print "\\gdef\\SVNLastChangedRev{" LastChangedRev "}%" + print "\\gdef\\SVNLastChangedAuthor{" LastChangedAuthor "}%" + print "\\gdef\\SVNLastChangedDate{" LastChangedDate "}%" + print "\\gdef\\SVNRepositoryUuid{" RepositoryUuid "}%" + if (full==1) { + print "\\gdef\\SVNPath{" Path "}%" + print "\\gdef\\SVNName{" Name "}%" + print "\\gdef\\SVNUrl{" Url "}%" + print "\\gdef\\SVNNodeKind{" NodeKind "}%" + print "\\gdef\\SVNRepositoryRoot{" RepositoryRoot "}%" + } +### Write generic version control macros. + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\SVNRevision}%" + print "\\gdef\\VCAuthor{\\SVNLastChangedAuthor}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + MaxRevision = 0 + } + +### Process output of "svn status". + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } + +} diff --git a/support/vc/svn-windows/vc-svn.awk b/support/vc/svn-windows/vc-svn.awk new file mode 100644 index 0000000000..37179028a2 --- /dev/null +++ b/support/vc/svn-windows/vc-svn.awk @@ -0,0 +1,136 @@ +# This is file 'vc-svn.awk' from the vc bundle for TeX. +# The original file can be found at CTAN:support/vc. +# This file is Public Domain. +BEGIN { + +### Process output of "svn info". + if (script=="info") { + MaxRevision = 0 + } + +### Process output of "svn status". + if (script=="status") { + modified = 0 + } + +} + + + +### Process output of "svn info". +### Save all lines of the current record in a corresponding variable. +script=="info" && /^Path:/ { RecPath = $0; next } +script=="info" && /^Name:/ { RecName = $0; next } +script=="info" && /^URL:/ { RecUrl = $0; next } +script=="info" && /^Repository Root:/ { RecRepositoryRoot = $0; next } +script=="info" && /^Repository UUID:/ { RecRepositoryUuid = $0; next } +script=="info" && /^Revision:/ { RecRevision = $2; next } +script=="info" && /^Node Kind:/ { RecNodeKind = $0; next } +script=="info" && /^Last Changed Author:/ { RecLastChangedAuthor = $0; next } +script=="info" && /^Last Changed Rev:/ { RecLastChangedRevision = $0; next } +script=="info" && /^Last Changed Date:/ { RecLastChangedDate = $0; next } +script=="info" && /^[\r]*$/ { +### If revision number of the new record is higher, +### save all lines from the new record. + if (RecRevision > MaxRevision) { + MaxPath = RecPath + MaxName = RecName + MaxUrl = RecUrl + MaxRepositoryRoot = RecRepositoryRoot + MaxRepositoryUuid = RecRepositoryUuid + MaxRevision = RecRevision + MaxNodeKind = RecNodeKind + MaxLastChangedAuthor = RecLastChangedAuthor + MaxLastChangedRev = RecLastChangedRevision + MaxLastChangedDate = RecLastChangedDate + } +} + +### Process output of "svn status". +### File with local modifications? +script=="status" && /^[^ ?]/ { modified = 1 } +### File with property modifications? +script=="status" && /^.[^ ]/ { modified = 2 } + + + +END { + +### Process output of "svn info". + if (script=="info") { +### Remove possible Windows line endings (e.g., for Msys). + gsub("\r$", "", MaxPath) + gsub("\r$", "", MaxName) + gsub("\r$", "", MaxUrl) + gsub("\r$", "", MaxRepositoryRoot) + gsub("\r$", "", MaxRepositoryUuid) + gsub("\r$", "", MaxRevision) + gsub("\r$", "", MaxNodeKind) + gsub("\r$", "", MaxLastChangedAuthor) + gsub("\r$", "", MaxLastChangedRev) + gsub("\r$", "", MaxLastChangedDate) +### Escape % characters for TeX compatibility. + gsub("%", "\\%", MaxUrl) + gsub("%", "\\%", MaxRepositoryRoot) +### Extract relevant information from variables. + Path = substr(MaxPath, 2+match(MaxPath, ":")) + Name = substr(MaxName, 2+match(MaxName, ":")) + Url = substr(MaxUrl, 2+match(MaxUrl, ":")) + RepositoryRoot = substr(MaxRepositoryRoot, 2+match(MaxRepositoryRoot, ":")) + RepositoryUuid = substr(MaxRepositoryUuid, 2+match(MaxRepositoryUuid, ":")) + Revision = MaxRevision + NodeKind = substr(MaxNodeKind, 2+match(MaxNodeKind, ":")) + LastChangedAuthor = substr(MaxLastChangedAuthor, 2+match(MaxLastChangedAuthor, ":")) + LastChangedRev = substr(MaxLastChangedRev, 2+match(MaxLastChangedRev, ":")) + LastChangedDate = substr(MaxLastChangedDate, 2+match(MaxLastChangedDate, ":")) + LongDate = substr(LastChangedDate, 1, 25) + DateRAW = substr(LongDate, 1, 10) + DateISO = DateRAW + DateTEX = DateISO + gsub("-", "/", DateTEX) + Time = substr(LongDate, 12, 14) +### Write file identification to vc.tex. + print "%%% This file has been generated by the vc bundle for TeX." + print "%%% Do not edit this file!" + print "%%%" +### Write Subversion specific macros. + print "%%% Define Subversion specific macros." + print "\\gdef\\SVNRevision{" Revision "}%" + print "\\gdef\\SVNLastChangedRev{" LastChangedRev "}%" + print "\\gdef\\SVNLastChangedAuthor{" LastChangedAuthor "}%" + print "\\gdef\\SVNLastChangedDate{" LastChangedDate "}%" + print "\\gdef\\SVNRepositoryUuid{" RepositoryUuid "}%" + if (full==1) { + print "\\gdef\\SVNPath{" Path "}%" + print "\\gdef\\SVNName{" Name "}%" + print "\\gdef\\SVNUrl{" Url "}%" + print "\\gdef\\SVNNodeKind{" NodeKind "}%" + print "\\gdef\\SVNRepositoryRoot{" RepositoryRoot "}%" + } +### Write generic version control macros. + print "%%% Define generic version control macros." + print "\\gdef\\VCRevision{\\SVNRevision}%" + print "\\gdef\\VCAuthor{\\SVNLastChangedAuthor}%" + print "\\gdef\\VCDateRAW{" DateRAW "}%" + print "\\gdef\\VCDateISO{" DateISO "}%" + print "\\gdef\\VCDateTEX{" DateTEX "}%" + print "\\gdef\\VCTime{" Time "}%" + print "\\gdef\\VCModifiedText{\\textcolor{red}{with local modifications!}}%" + print "%%% Assume clean working copy." + print "\\gdef\\VCModified{0}%" + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + MaxRevision = 0 + } + +### Process output of "svn status". + if (script=="status") { + print "%%% Is working copy modified?" + print "\\gdef\\VCModified{" modified "}%" + if (modified==0) { + print "\\gdef\\VCRevisionMod{\\VCRevision}%" + } else { + print "\\gdef\\VCRevisionMod{\\VCRevision~\\VCModifiedText}%" + } + } + +} diff --git a/support/vc/svn-windows/vc.bat b/support/vc/svn-windows/vc.bat new file mode 100644 index 0000000000..0f7a5e035c --- /dev/null +++ b/support/vc/svn-windows/vc.bat @@ -0,0 +1,24 @@ +@echo off +REM This is file 'vc.bat' from the vc bundle for TeX. +REM The original file can be found at CTAN:support/vc. +REM This file is Public Domain. + +setlocal +REM Parse command line options. +set full=0 +set mod=0 +:loopParams +if "%1" NEQ "" ( + if "%1"=="-f" (set full=1) else if "%1"=="-m" (set mod=1) else ( + echo usage: vc [-f] [-m] + exit /b 1 + ) + shift + goto loopParams +) +REM English locale. +set LC_ALL=C +svn info -R . |gawk -v script=info -v full=%full% -f vc-svn.awk > vc.tex +if "%mod%"=="1" ( + svn status |gawk -v script=status -f vc-svn.awk >> vc.tex +) diff --git a/support/vc/vc-manual.pdf b/support/vc/vc-manual.pdf Binary files differnew file mode 100644 index 0000000000..be85f81017 --- /dev/null +++ b/support/vc/vc-manual.pdf diff --git a/support/vc/vc-manual.tex b/support/vc/vc-manual.tex new file mode 100644 index 0000000000..dd203fe7e6 --- /dev/null +++ b/support/vc/vc-manual.tex @@ -0,0 +1,702 @@ +\documentclass[11pt]{article} +\usepackage[ansinew]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{textcomp} +\usepackage{tabularx} +\usepackage{booktabs} +\usepackage{multicol} + +\immediate\write18{sh ./vc} +\input{vc} +\usepackage[rgb,x11names]{xcolor} +\usepackage{prelim2e} +\renewcommand*{\PrelimWords}{\textnormal{\small The \pkg\ bundle}} +\renewcommand*{\PrelimText}{\textnormal{\small\textcolor{black!40}{\PrelimWords, + \VCAuthor\ -- \VCDateISO\ -- commit \texttt{\VCRevision}}}} + +\usepackage{listings} +\lstloadlanguages{[LaTeX]TeX, sh} +\colorlet{lstcolTeX}{green!50!black} +\colorlet{lstcoltext}{black} +\colorlet{lstcolshell}{blue!50!black} +\lstset{basicstyle=\small\ttfamily, keywordstyle={}, commentstyle={}, + columns=flexible, showspaces=false, showstringspaces=false, + aboveskip=12pt, belowskip=12pt, frame=tb, + framesep=8pt, framerule=2pt, xleftmargin=10pt, + xrightmargin=10pt, framexleftmargin=10pt, framexrightmargin=10pt +} +\lstdefinestyle{shell}{language=sh, rulecolor=\color{lstcolshell!25}} +\lstdefinestyle{TeX}{language=TeX, rulecolor=\color{lstcolTeX!25}} +\lstdefinestyle{text}{language=TeX, rulecolor=\color{lstcoltext!25}} +\lstnewenvironment{listing}[1][] +{\lstset{#1}} +{} +\newlength{\sbslistingwd} +\setlength{\sbslistingwd}{.48\linewidth} + +\usepackage{hyperref} +\hypersetup{ + pdftitle={The vc bundle}, + pdfauthor={Roland Hieber, Stephan Hennig} +} +\hypersetup{ + pdfstartview={XYZ null null null},% Zoom factor is determined by viewer. + colorlinks, + linkcolor=RoyalBlue3, + urlcolor=Chocolate4, + citecolor=SpringGreen3 +} + +\newcommand*{\pkg}{\texttt{vc}} +\newcommand*{\pkgversion}{v0.6} +\newcommand*{\descr}[1]{$\langle$#1$\rangle$} +\newcommand*{\full}{\makebox[0pt][r]{${}^{\mbox{\footnotesize\textasteriskcentered}}$}} +\begin{document} +\author{Roland Hieber\thanks{rohieb+ctan@rohieb.name} \and + Stephan Hennig\thanks{stephanhennig@arcor.de}} +\title{The \pkg\ bundle\thanks{This document describes the \pkg\ bundle + \pkgversion}} +\maketitle +\begin{abstract} + This is a script based approach to version control for \TeX\ + documents. It works more reliably than keyword substitution based + approaches, since it tracks \emph{all} files in a working copy, not + only \texttt{.tex} files. The \pkg\ bundle works with \LaTeX\ and + plain \TeX. Currently, Bazaar, Git, Mercurial and Subversion are supported. +\end{abstract} +\begin{multicols}{2} +\tableofcontents +\end{multicols} + + + +\section{Introduction} +There is an inherent problem with \LaTeX\ and version control software +as soon as you're dealing with files generated by an external tool, +\emph{e.g.}, graphics. Packages such as \texttt{svn-multi} can't track +neither binary files, nor source files of graphics compiled by, +\emph{e.g.}, MetaPost. For that reason, if you check-in a new revision +that only touches a graphic file, your VCS package would never know a +check-in has happened and tell you the old revision number (or date or +other meta data) in your documents. + +At least, the problem is only of temporary nature and as soon as you +check-in a file that is tracked by the VCS package, \emph{i.e.}, a +\texttt{.tex} file, you'll get the correct revision number again. But +traditional VCS packages, that build on the keyword substitution feature +provided by some VCS can't track revision information \emph{reliably}, +as they look at \texttt{.tex} files only. + +To enable reliable tracking of revision information one has to look at +\emph{all} files in a working copy. Since for non-source files the +keyword substitution feature doesn't work, another approach has been +taken here. This bundle consists of some scripts that directly talk +with the VCS backend to get the desired information and write them to a +file \texttt{vc.tex}. This file can then be included into your document +sources. + +The \pkg\ bundle works with \LaTeX\ as well as plain \TeX. Currently, +Bazaar, Git, Mercurial and Subversion are supported. Additional contributions are +welcome! + + + +\section{Usage} +\label{sec:usage} +Doing version control with the \pkg\ bundle is very easy. While for +other \LaTeX\ VCS packages you need to activate keyword substitution and +modify all \texttt{.tex} source files, these steps aren't necessary for +the \pkg\ bundle. You just have to copy two files to your project's +working copy and add one line to your \TeX\ preamble. + + +\subsection{Installation} +\label{sec:installation} +Ok, lets set-up the project repository. As a prerequisite, the scripts +of the \pkg\ bundle need \texttt{GNU awk}. Please install this first.% +\footnote{For Windows you can find \texttt{gawk} in the + \texttt{GNUWin32} utilities. Alternative ports can be found in + \texttt{Msys} or \texttt{Cygwin}.} % + +The \pkg\ bundle consists of three files: a shell script, an AWK script, +and an automatically generated \TeX\ file. For Unix and Windows the set +of files might be\newline +\begin{minipage}{\textwidth} + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=text, title=Unix\strut] +vc +vc-bzr.awk +vc.tex + \end{listing} + \end{minipage}\hfill + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=text, title=Windows\strut] +vc.bat +vc-bzr.awk +vc.tex + \end{listing} + \end{minipage} +\end{minipage} +Note, depending on your VCS the AWK script might be any of +\texttt{vc-bzr.awk}, \texttt{vc-git.awk}, \texttt{vc-hg.awk} or \texttt{vc-svn.awk}. +Additionally, while the AWK scripts have the same names on Unix and +Windows, the \pkg\ bundle provides them with different line endings. +So, watch out to take the right one for your VCS and~OS. + +Installation is a one-step procedure (with two additional optional +steps). +\begin{enumerate} +\item Copy the two script files\newline + \begin{tabular}{l@{\hspace{5em}}l} + \textbullet~\texttt{vc} & (or \texttt{vc.bat} for Windows)\\ + \textbullet~\texttt{vc-bzr.awk} & (or \texttt{vc-git.awk} or \texttt{vc-hg.awk} or \texttt{vc-svn.awk})\\ + \end{tabular}\newline + into the top-level directory of your project's working copy. + +\item \emph{(Optionally)} You can instruct your VCS software to ignore + all three \texttt{vc} related files. Please consult the manual of + your VCS software about this. Question~\ref{vcIgnoreFiles} in + Section~\ref{sec:qa} contains some brief instructions for Bazaar, Git, Mercurial + and Subversion, too. + +\item \emph{(Optionally)} Personally, the author is used to check-in + both scripts into each project repository to have them available when + they are needed and ignore file \texttt{vc.tex} only. +\end{enumerate} + + +\subsection{Preparing documents} +\label{sec:preparing} +What remains to be done is adding this line +\begin{listing}[style=TeX] +\input{vc} +\end{listing} +to your main \LaTeX\ or plain \TeX\ document. That's it. + +\emph{Congratulations!} You have now access to several macros +containing VCS information in your \TeX\ document. The general macros +available are shown in table~\ref{tab:vcmacros}. + +\begin{table} + \centering\small + \begin{tabularx}{\textwidth}{l>{\raggedright\arraybackslash}X} + macro & meaning\\\addlinespace \toprule\addlinespace + \verb+\VCRevision+ & current (maximum) working copy revision number\\ + \verb+\VCAuthor+ & author of the last check-in operation\\ + \verb+\VCDateRAW+ & date of last check-in in native format of the VCS software\\ + \verb+\VCDateISO+ & date of last check-in in ISO format YYYY-MM-DD\\ + \verb+\VCDateTEX+ & date of last check-in in \TeX\ format YYYY/MM/DD\\ + \verb+\VCTime+ & time of last check-in\\ + \verb+\VCRevisionMod+ & as \verb+\VCRevision+, but with an additional note if the working copy contains modified files\\ + \verb+\VCModifiedText+& contains the note shown in macro \verb+\VCRevisionMod+ if there were modified files. This macro can be redefined by the user.\\ + \verb+\VCModified+ & \verb+0+ if there are no modified files in the working copy directory; \verb+1+ or \verb+2+ if there are modified files. In general you don't need this macro.\\ + \end{tabularx} + \caption{General version control macros.} + \label{tab:vcmacros} +\end{table} + +The most prominent information is probably the revision number, that can +be found in macro \verb+\VCRevision+. For Bazaar and Subversion this is +a plain number, for Git it is a 7-hexdigit hash (the truncated +40-hexdigit SHA1 commit hash), for Mercurial it is a 12-hexdigit hash (truncated from 40 symbols). Another macro that might be of interest +is \verb+\VCRevisionMod+. This macro is discussed in detail in +appendix~\ref{sec:localmod}. + +The remaining macros found in table~\ref{tab:vcmacros} contain author, +date (in different formats) and time of the last commit and should be +straightforward to use. + +The above mentioned macros are available for all supported systems and +in general should be sufficient. However, depending on the VCS software +you are using, there might be additional meta data available.% +\footnote{Such as the complete 40-hexdigit SHA1 commit hash for Git or Mercurial.} +Those data are stored in other macros that are discussed in +appendix~\ref{sec:notes}. + + +\subsection{Compiling documents} +\label{sec:compiling} +Before file \texttt{vc.tex} can be loaded in the document preamble, it +needs to be generated. Doing that is as easy as running the shell +script \texttt{vc} -- or \texttt{vc.bat} for Windows -- before (La)\TeX. +There are three ways to do this: +\begin{enumerate} +\item from a \texttt{Makefile} -- this is the preferred method, +\item via \verb+\write18+ -- another automatic solution, +\item manually -- not recommended (inconvenient and error-prone). +\end{enumerate} + +Here's how the script can be called from within a \LaTeX\ run via the +\verb+\write18+ feature. Add the two lines\newline +\begin{minipage}{\textwidth} + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=TeX, title=Unix\strut] +\immediate\write18{sh ./vc} +\input{vc} + \end{listing} + \end{minipage}\hfill + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=TeX, title=Windows\strut] +\immediate\write18{vc.bat} +\input{vc} + \end{listing} + \end{minipage} +\end{minipage} +to your document. If \LaTeX\ sees the first line, it immediately +executes the argument of \verb+\write18+ on the command-line. That is, +the script \texttt{vc} -- or \texttt{vc.bat} -- is executed and file +\texttt{vc.tex} is updated. On the second line \LaTeX\ reads-in the +newly generated file \texttt{vc.tex}. + +To make this work the \verb+\write18+ feature has to be enabled. By +default, it is disabled for security reasons. For MiK\TeX\ +\verb+\write18+ can be enabled by calling \LaTeX\ via +\begin{listing}[style=shell, escapechar=\#] +> latex -enable-write18 #\descr{document}# +\end{listing} +For other \LaTeX\ distributions, please consult the documentation. + +The \verb+\write18+ feature is not relevant if \texttt{vc} is called by +a \texttt{Makefile}. + +\nobreak +\bigskip +\nobreak +\begingroup +\raggedright +\itshape +Happy \TeX ing!\par +Stephan Hennig +\endgroup + + +\appendix +\section{Notes on supported VCS} +\label{sec:notes} + +\emph{To be completed.} VCS specific macros are prefixed \verb+\BZR+, +\verb+\GIT+, \verb+\HG+ or \verb+\SVN+. Tables~\ref{tab:vcBZRmacros} +to~\ref{tab:vcSVNmacros} show the additional macros available, depending +on your VCS. + +The macros marked by an asterisk might contains sensitive information +such as the path to a repository, file names, \emph{etc.} These macros +are only written to file \texttt{vc.tex} in \emph{full mode}. By +default, full mode is disabled. That is, distributing file +\texttt{vc.tex} along with your \TeX\ source files should be fairly +save, by default. + +To activate full mode script \texttt{vc} has to be called with +command-line option~\verb+-f+. This option should only be used with +care. + +\begin{table}[p] + \centering\small + \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X} + macro & meaning\\\addlinespace \toprule\addlinespace + \full\verb+\BZRBranchNick+ & branch nickname\\ + \verb+\BZRRevisionId+ & full revision id\\ + \verb+\BZRDate+ & date of the last revision\\ + \verb+\BZRBuildDate+ & current date\\ + \verb+\BZRRevNo+ & revision number\\ + \end{tabularx} + \caption{Bazaar specific version control macros.} + \label{tab:vcBZRmacros} +\end{table} + +\begin{table}[p] + \centering\small + \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X} + macro & meaning\\\addlinespace \toprule\addlinespace + \verb+\GITHash+ & 40-hexdigit SHA1 commit hash\\ + \verb+\GITAbrHash+ & abbreviated commit hash\\ + \verb+\GITParentHashes+ & parent hashes\\ + \verb+\GITAbrParentHashes+ & abbreviated parent hashes\\ + \verb+\GITAuthorName+ & author name\\ + \verb+\GITAuthorEmail+ & author e-mail\\ + \verb+\GITAuthorDate+ & author date\\ + \verb+\GITCommitterName+ & committer name\\ + \verb+\GITCommitterEmail+ & committer e-mail\\ + \verb+\GITCommitterDate+ & committer date\\ + \end{tabularx} + \caption{Git specific version control macros.} + \label{tab:vcGITmacros} +\end{table} + +\begin{table}[p] + \centering\small + \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X} + macro & meaning\\\addlinespace \toprule\addlinespace + \verb+\HGHash+ & 40-hexdigit SHA1 commit hash\\ + \verb+\HGAbrHash+ & abbreviated commit hash\\ + \verb+\HGBranch+ & commit branch\\ + \verb+\HGFirstParentHash+ & first parent hash\\ + \verb+\HGSecondParentHash+ & second parent hash (\textit{All zeroes means one-parent revision}) \\ + \verb+\HGAbrFirstParentHash+ & abbreviated first parent hash\\ + \verb+\HGAbrSecondParentHash+ & abbreviated second parent hash \\ + \verb+\HGAuthorName+ & author name\\ + \verb+\HGAuthorEmail+ & author e-mail\\ + \verb+\HGAuthorDate+ & author date\\ + \end{tabularx} + \caption{Mercurial specific version control macros.} + \label{tab:vcHGmacros} +\end{table} + +\begin{table}[p] + \centering\small + \begin{tabularx}{\textwidth}{p{12em}>{\raggedright\arraybackslash}X} + macro & meaning\\\addlinespace \toprule\addlinespace + \full\verb+\SVNPath+ & path to an arbitrary file or directory, that + is part of the last commit\\ + \full\verb+\SVNName+ & \verb+\SVNPath+'s name without path\\ + \full\verb+\SVNUrl+ & path of \verb+\SVNPath+ in the repository\\ + \full\verb+\SVNNodeKind+ & node kind of \verb+\SVNPath+ (file, + directory, \emph{etc.})\\ + \full\verb+\SVNRepositoryRoot+ & repository root URL\\ + \verb+\SVNRevision+ & revision number of \verb+\SVNPath+\\ + \verb+\SVNLastChangedRev+ & revision number of \verb+\SVNPath+\\ + \verb+\SVNLastChangedAuthor+ & author of the last commit\\ + \verb+\SVNLastChangedDate+ & date of the last commit\\ + \verb+\SVNRepositoryUuid+ & repository UUID\\ + \end{tabularx} + \caption{Subversion specific version control macros.} + \label{tab:vcSVNmacros} +\end{table} + +\clearpage + + +\section{Checking for local modifications} +\label{sec:localmod} +Some people prefer to be notified, if a document is compiled from a +dirty working copy, \emph{i.e.}, from a state not corresponding to a +committed revision. This feature has been implemented in the \pkg\ +bundle, but is disabled by default (see below). + +Macro \verb+\VCRevisionMod+ is similar to \verb+\VCRevision+, but it has +an additional message appended to the revision number, if there are any +modified files in the working copy. + +The actual message is defined in macro \verb+\VCModifiedText+ and can be +redefined by the user. The default definition is +\begin{listing}[style=TeX] +\gdef\VCModifiedText{\textcolor{red}{with local modifications!}} +\end{listing} +That is, package \texttt{color} has to be loaded in the document +preamble if macro \verb+\VCRevisionMod+ is used or macro +\verb+\VCModifiedText+ has to be redefined accordingly. + +By default, searching for local modifications is disabled to prevent +slowing down execution of the scripts. To check a working copy for +modified files script \texttt{vc} has to be called with the switch +\texttt{--m}. The \verb+\write18+ example from +section~\ref{sec:compiling} now reads:\newline +\begin{minipage}{\textwidth} + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=TeX, title=Unix\strut] +\immediate\write18{sh ./vc -m} +\input{vc} + \end{listing} + \end{minipage}\hfill + \begin{minipage}[t]{\sbslistingwd} + \begin{listing}[style=TeX, title=Windows\strut] +\immediate\write18{vc.bat -m} +\input{vc} + \end{listing} + \end{minipage} +\end{minipage} + +Note, since distributing documents not corresponding to a committed +revision is bad style, it is wise make sure by other means (a release +procedure), that distributed documents never contain uncommitted +changes. Therefore, a note, say, next to the revision number, doesn't +really provide any additional information. If you think you need such a +note, something might be wrong with your release procedure. + + + +\section{Questions and answers} +\label{sec:qa} + +\newcommand*{\qfont}{\sffamily\bfseries} +\newcommand*{\question}[2]{% + \expandafter\gdef\csname #1\endcsname{#2}% +\item\label{#1}\csname #1\endcsname% +} +\newcommand{\answer}[1]{% + \medskip\par + {\noindent\qfont\ref{#1}.~\csname #1\endcsname\par} + \nobreak\noindent\ignorespaces% +} + +\begin{enumerate} + \qfont% + \setlength{\itemsep}{4pt}% + \setlength{\parskip}{0pt}% + +\question{vcHowOften}{How often do I need to run the script \texttt{vc}? + Every time before \TeX\ is run?} + +\question{vcWhyNoData}{Why are VCS data not updated in my document?} + +\question{vcHowToInsert}{How can I print VCS data at arbitrary places in + my document?} + +\question{vcDraftMode}{I want to have VCS data in the document only in + draft mode!} + +\question{vcDateFormat}{How can I change the date format?} + +\question{vcVcsSpecifics}{How can I access software specific VCS + information, \emph{e.g.}, Git's 40-hexdigit commit hash?} + +\question{vcWhyGdef}{Why are macros defined with \texttt{\textbackslash + gdef} instead of \texttt{\textbackslash newcommand} in file + \texttt{vc.tex}?} + +\question{vcVCRevisionMod-m}{Macro \texttt{\textbackslash VCRevisionMod} + only shows the revision number, even if there are modified files in my + working copy.} + +\question{vcVCRevisionMod-unskip}{In macro \texttt{\textbackslash + VCRevisionMod}, how can I get rid of the horizontal skip between + revision number and the message?} + +\question{vcIgnoreFiles}{How do I ignore files with my VCS?} + +\question{vcPerFile}{Is it possible to get per-file revision data with + the \pkg\ bundle? This were quite handy when working with a + multi-file document (say, each file is a chapter). After changing one + file, the information could be used to check if an old print-out of + another chapter is current.} + +\question{vcLicense}{Can I put files of the \pkg\ bundle into a private, + public or commercial repository?} +\end{enumerate} + +\answer{vcHowOften} First, it is not recommended to run the script +manually, but automatically, either from a \texttt{Makefile} or directly +from \LaTeX\ via \verb+\write18+. For that reason, it shouldn't matter +how often the script is called. + +To answer the question: If you run the script \texttt{vc} manually, it +is sufficient to do that once after each check-in or update operation. +The only advantage of running the script before \emph{every} \TeX\ run +is that it keeps macro \verb+\VCRevisionMod+ up-to-date w.r.t.\@ local +modifications (when called with the \texttt{--m} switch). + +Therefore, a fourth way to run script \texttt{vc} were to put it into a +VCS hook that is called after check-in or update operations. There are +no examples for this solution, since it heavily depends on the +underlying VCS. Additionally, some VCS might not provide enough hooks +to cover all operations that modify a working copy. + +\answer{vcWhyNoData} Make sure script \texttt{vc} is run between +check-in operations and the \TeX\ run. In case the script is called +from \TeX\ via \verb+\write18+ (see section~\ref{sec:compiling}), you've +probably just forgotten to enable that feature. Please, refer to the +manual of your \TeX\ distribution to learn how to enable +\verb+\write18+. + +\answer{vcHowToInsert} This question is covered in the UK-TeX-FAQ. +Depending on where you want to put VCS information---header, footer, +page background---you might be interested in the following links: +\begin{itemize} +\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fancyhdr} +\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=watermark} +\item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=abspos} +\end{itemize} +Here is some code to put the revision number together with check-in date +and time into the foot line with packages \texttt{fancyhdr} and +\texttt{scrpage2}: +\begin{listing}[style=TeX] +\usepackage{fancyhdr} +\pagestyle{fancy} +\fancyfoot[LE,LO]{Rev: \VCRevision} +\fancyfoot[RE,RO]{Time: \VCDateISO \VCTime} +\end{listing} +\begin{listing}[style=TeX] +\usepackage{scrpage2} +\pagestyle{scrheadings} +\lefoot{Rev: \VCRevision} +\lofoot{Rev: \VCRevision} +\refoot{Time: \VCDateISO \VCTime} +\rofoot{Time: \VCDateISO \VCTime} +\end{listing} + +Another source of information might be the \TeX\ catalogue: +\begin{itemize} +\item \url{http://texcatalogue.sarovar.org/bytopic.html#revision} +\end{itemize} +In this manual, the \texttt{prelim2e.sty} package has been used to +present VCS information. See file \texttt{vc-manual.tex} to learn how +the foot line has been set up in this document. + +\answer{vcDraftMode} Have a look at the \texttt{ifdraft} package from +the \texttt{oberdiek} bundle. + +\answer{vcDateFormat} Package \texttt{isodate} provides means to convert +between various (localized) date formats. + +\answer{vcVcsSpecifics} The general VCS information provided in macros +prefixed \verb+\VC+ are available for all supported version control +systems. However, there are additional information available for some +VCS that are not for others. These information are stored in macros +that have a VCS specific prefix (\emph{cf.} appendix~\ref{sec:notes} and +file \texttt{vc.tex}). As an example, Git's 40-hexdigit commit hash is +provided in a macro \verb+\GITHash+. You can either use this macro +directly or redefine \verb+\VCRevision+ to show the long hash as +follows: +\begin{listing}[style=TeX] +\renewcommand*{\VCRevision}{\GITHash} +\end{listing} +But keep in mind, that persons, unfamiliar with version control software +or Git in particular, might be irritated by cryptic information on every +document page. + +\answer{vcWhyGdef} This is plain \TeX\ syntax and this works with +\LaTeX, too. If you're using \LaTeX\ you can of course use +\verb+\renewcommand+ to redefine macros, \emph{e.g.}, \verb+\VCRevision+ +as shown in the answer to the preceeding question. + +\answer{vcVCRevisionMod-m} Call script \texttt{vc} with the \texttt{--m} +switch, see appendix~\ref{sec:localmod}. + +\answer{vcVCRevisionMod-unskip} By default, the definition of macro +\verb+\VCRevisionMod+ is +\begin{listing}[style=TeX] +\gdef\VCRevisionMod{\VCRevision~\VCModifiedText} +\end{listing} +To remove the horizontal space before macro \verb+\VCModifiedText+ just +start its definition with \verb+\unskip+, \emph{e.g.}, +\begin{listing}[style=TeX] +\gdef\VCModifiedText{\unskip, modified} +\end{listing} + +\answer{vcIgnoreFiles} \emph{If you don't know how to configure your + VCS, please read its documentation carefully before doing any of the + steps shown below!} + +Here are some short instructions for ignoring file \texttt{vc.tex} in +Bazaar, Git, Mercurial and Subversion: +\begin{description} +\item[Bazaar] In the directory containing the script files issue the + following commands on the command line: +\begin{listing}[style=shell] +> bzr ignore vc.tex +> bzr commit .bzrignore +\end{listing} +This creates a file \texttt{.bzrignore} that contains ignore patterns +and puts that file under version control. + +\item[Git] In the directory containing the script files create a file + \texttt{.gitignore} containing the line +\begin{listing}[style=text] +vc.tex +\end{listing} +and put \texttt{.gitignore} under version control: +\begin{listing}[style=shell] +> git add .gitignore +> git commit .gitignore +\end{listing} + +\item[Mercurial] In the directory containing the script files create a file + \texttt{.hgignore} containing the line +\begin{listing}[style=text] +vc.tex +\end{listing} +and put \texttt{.hgignore} under version control: +\begin{listing}[style=shell] +> hg add .hgignore +> hg commit .hgignore +\end{listing} + +\item[Subversion] In the directory containing the script files issue the + following commands on the command line: +\begin{listing}[style=shell] +> svn propedit svn:ignore . +> svn commit +\end{listing} +The first command will open an editor. Add the line +\begin{listing}[style=text] +vc.tex +\end{listing} +save the file, close the editor and commit the changes. +\end{description} + +\answer{vcPerFile} This sounds like you're interested in tracking +changes instead of just revision data. Note, that tracking changes and +documenting revision data for later reference are fundamentally +different requirements. The \pkg\ bundle has only been written with the +latter use-case in mind. In fact, the scripts of the \pkg\ bundle try +hard to be ignorant of individual file revision data. + +There are three possible solutions (that do without \pkg): +\begin{enumerate} +\item To check whether files have changed between revisions one can use: +\begin{listing}[style=shell, escapechar=\#] +> svn diff -r #\descr{r1}#:#\descr{r2}# #\descr{file}# +\end{listing} +Of course, this is an on-line only solution, while you can check printed +numbers off-line and anywhere. That's not to say it's better or worse, +but it requires a slightly different work-flow. (For example, to pass +\emph{anybody} the new document version, therefore avoiding the question +if and where two print-outs differ.) + +\item If you want to track changes instead of revision numbers, have a + look at this item in UK-TeX-FAQ: + \begin{itemize} + \item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=changebars} + \end{itemize} + +\item Packages \texttt{svninfo} or \texttt{svn-multi} and \pkg\ can + perfectly be used together to get reliable total revision data as well + as per-file revision data. Although, this may sound like overkill it + could fit some use-cases. For alternative version control packages + see + \begin{itemize} + \item \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=RCS} + \item \url{http://texcatalogue.sarovar.org/bytopic.html#revision} + \end{itemize} +\end{enumerate} + +\answer{vcLicense} This is perfectly possible. The \pkg\ bundle has +been put into the Public Domain to remove any usage restrictions. + + + +\section{Comparision with alternative VCS packages} +\label{sec:comparision} +The \pkg\ bundle +\begin{itemize} +\item looks at all files in a working copy to get reliable revision + information, +\item doesn't provide per-file revision data, +\item doesn't use keyword substitution, +\item works with \LaTeX\ and plain \TeX, +\item supports Bazaar, Git, Mercurial and Subversion, +\item needs an AWK interpreter. +\item Running the scripts might become noticeable on projects with many + files. +\end{itemize} + + + +\section{To do} +\label{sec:todo} +\begin{itemize} +\item Base Git scripts on plumbing commands. +\item Rewrite (and merge) scripts in Perl. +\item Add support for other VCS software. Contributions are welcome! +\end{itemize} + + + +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-PDF-mode: t +%%% TeX-master: t +%%% End: |