summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gitlog
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/gitlog
Initial commit
Diffstat (limited to 'macros/latex/contrib/gitlog')
-rw-r--r--macros/latex/contrib/gitlog/README.md26
-rw-r--r--macros/latex/contrib/gitlog/gitHeadLocal.gin17
-rw-r--r--macros/latex/contrib/gitlog/gitlog.bbx45
-rw-r--r--macros/latex/contrib/gitlog/gitlog.dbx17
-rw-r--r--macros/latex/contrib/gitlog/gitlog.pdfbin0 -> 93972 bytes
-rw-r--r--macros/latex/contrib/gitlog/gitlog.sample.bib210
-rw-r--r--macros/latex/contrib/gitlog/gitlog.sty111
-rw-r--r--macros/latex/contrib/gitlog/gitlog.tex364
8 files changed, 790 insertions, 0 deletions
diff --git a/macros/latex/contrib/gitlog/README.md b/macros/latex/contrib/gitlog/README.md
new file mode 100644
index 0000000000..2e212d6150
--- /dev/null
+++ b/macros/latex/contrib/gitlog/README.md
@@ -0,0 +1,26 @@
+# gitlog.sty -- Typeset git logs as bibliographies
+
+The *gitlog* package allows git change log history to be incorporated into LaTeX documents; the log data is obtained from the git distributed version control system.
+
+The current release (0.0.beta) is a proof-of-concept release to allow users an early evaluation and to attract ideas and support.
+
+Requests and suggestions, as well as code contributions are welcome, via email, or as issues or pull requests on either Github or Bitbucket. The repository URLs are:
+
+* https://github.com/Hightor/gitlog/tree/develop
+* https://bitbucket.org/brentl/gitlog/commits/branch/develop
+
+### Licencing
+
+Copyright 2015 Brent Longborough. *gitlog* is licenced under the LPPL. For more details, please see the accompanying manual: gitlog.pdf.
+
+### Change History
+
+Current Release: 0.0.beta 2015-11-22. Probably not suitable for high-quality production environments!
+
+Please see gitlog.pdf in the package documentation directory for release history and a full changelog.
+
+This work consists of these files:
+
+ gitlog.sty, gitlog.bbx, gitlog.dbx,
+ gitlog.tex, gitlog.sample.bib, gitHeadLocal.gin,
+ gitlog.pdf, and README.md (this file)
diff --git a/macros/latex/contrib/gitlog/gitHeadLocal.gin b/macros/latex/contrib/gitlog/gitHeadLocal.gin
new file mode 100644
index 0000000000..b359b29e6e
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitHeadLocal.gin
@@ -0,0 +1,17 @@
+\usepackage[%
+ shash={3b2c518},
+ lhash={3b2c51811e0929696723f1f777ac0cc6ba646727},
+ authname={Brent Longborough},
+ authemail={brent@longborough.org},
+ authsdate={2015-11-21},
+ authidate={2015-11-21 23:48:15 +0000},
+ authudate={1448149695},
+ commname={Brent Longborough},
+ commemail={brent@longborough.org},
+ commsdate={2015-11-21},
+ commidate={2015-11-21 23:48:15 +0000},
+ commudate={1448149695},
+ refnames={ (HEAD -> CTAN)},
+ firsttagdescribe={0.0.beta-1-g3b2c518},
+ reltag={0.0.beta-1-g3b2c518}
+ ]{gitexinfo} \ No newline at end of file
diff --git a/macros/latex/contrib/gitlog/gitlog.bbx b/macros/latex/contrib/gitlog/gitlog.bbx
new file mode 100644
index 0000000000..87e24ec281
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.bbx
@@ -0,0 +1,45 @@
+\ProvidesFile{gitlog.bbx}[2015/11/22 0.0.beta]
+
+\defbibenvironment{bibliography}
+ {\list
+ {\printfield{entrykey}}%
+ {\setlength{\leftmargin}{5em}%
+ \setlength{\labelwidth}{0em}%
+ \setlength{\itemindent}{-\leftmargin}%
+ % \setlength{\itemindent}{0pt}%
+ \setlength{\itemsep}{\bibitemsep}%
+ % \addtolength{\leftmargin}{\labelsep}%
+ \setlength{\parsep}{\bibparsep}%
+ \renewcommand*{\makelabel}[1]{%
+ \makebox[5em]{\ttfamily##1}}}}
+ {\endlist}
+ {\item}
+
+\newbibmacro*{begentry}{}
+\newbibmacro*{finentry}{\finentry}
+
+\DeclareBibliographyDriver{gitcommit}{%
+ \usebibmacro{bibindex}%
+ \usebibmacro{begentry}%
+ \usebibmacro{title}%
+ \newblock%
+ \usebibmacro{date+author}%
+ \usebibmacro{finentry}}
+
+\newbibmacro*{commithash}{%
+ \printfield{commithash}%
+}
+
+% \newbibmacro*{entrykey}{%
+ % \href{https://github.com/Hightor/gitlog/commit/\thefield{commithash}}{\printfield{entrykey}}%
+% }
+
+% \DeclareFieldFormat{entrykey}{%
+ % \IfStrEq{}{\gitLog@github}{%
+ % #1
+ % }{%
+ % \href{https://github.com/\gitLog@github/commit/\thefield{commithash}}{#1}
+ % }
+% }
+
+\endinput
diff --git a/macros/latex/contrib/gitlog/gitlog.dbx b/macros/latex/contrib/gitlog/gitlog.dbx
new file mode 100644
index 0000000000..47d381d4cc
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.dbx
@@ -0,0 +1,17 @@
+\ProvidesFile{gitlog.dbx}[2015/11/22 0.0.beta]
+
+\DeclareDatamodelEntrytypes{gitcommit}
+\DeclareDatamodelFields[type=field,datatype=verbatim]{
+ title,
+}
+\DeclareDatamodelFields[type=field,datatype=literal]{
+ commithash,
+}
+\DeclareDatamodelEntryfields[gitcommit]{
+ title,
+ author,
+ date,
+ commithash,
+}
+
+\endinput
diff --git a/macros/latex/contrib/gitlog/gitlog.pdf b/macros/latex/contrib/gitlog/gitlog.pdf
new file mode 100644
index 0000000000..7f817b5e0d
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.pdf
Binary files differ
diff --git a/macros/latex/contrib/gitlog/gitlog.sample.bib b/macros/latex/contrib/gitlog/gitlog.sample.bib
new file mode 100644
index 0000000000..3deefefe7f
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.sample.bib
@@ -0,0 +1,210 @@
+@gitcommit{9dce109,
+ author = {Brent Longborough},
+ date = {2015-11-15},
+ title = {Initial commit
+},
+ commithash = {9dce10970bb6be976ce59f76dd28e52abeb3b103} }
+@gitcommit{f558cdd,
+ author = {Brent Longborough},
+ date = {2015-11-15},
+ title = {First code to build pseudo-bibfile
+},
+ commithash = {f558cddc5a95acb1c081ead6f6e81cb9941941a0} }
+@gitcommit{240f4c9,
+ author = {Brent Longborough},
+ date = {2015-11-15},
+ title = {Added data model (not working) - now we step back a bit
+},
+ commithash = {240f4c9dbb22631f6098fbe45c409ef58cdddb09} }
+@gitcommit{b4629f6,
+ author = {Brent Longborough},
+ date = {2015-11-16},
+ title = {First working version full of restrictions
+},
+ commithash = {b4629f6bb7504b2d6e4a677294a761e1d1d5c659} }
+@gitcommit{7f69aba,
+ author = {Brent Longborough},
+ date = {2015-11-16},
+ title = {Merge branch 'feature/Basic.Function' into develop
+},
+ commithash = {7f69aba7f0c053050cf5bc4dd88c9d42d41180a8} }
+@gitcommit{d651d24,
+ author = {Brent Longborough},
+ date = {2015-11-17},
+ title = {Gradually improving things (especially understanding)
+},
+ commithash = {d651d249a3a14fd270a0f40e5d8124f6c552cc5b} }
+@gitcommit{4c1dd2c,
+ author = {Brent Longborough},
+ date = {2015-11-17},
+ title = {Making an MWE for TeX.SX
+},
+ commithash = {4c1dd2c540ff8a2f2976d972d15071c1f54f9379} }
+@gitcommit{9ed8b6f,
+ author = {Brent Longborough},
+ date = {2015-11-17},
+ title = {commithash display solved
+},
+ commithash = {9ed8b6fa06f031900ac4e145e44da4dd3469a3ba} }
+@gitcommit{601242b,
+ author = {Brent Longborough},
+ date = {2015-11-17},
+ title = {Linking the change log to GitHub!
+},
+ commithash = {601242ba4d9ad8b92bec389a06a98ef80630d7d5} }
+@gitcommit{981d564,
+ author = {Brent Longborough},
+ date = {2015-11-17},
+ title = {Merge branch 'feature/Basic.Function' into develop
+},
+ commithash = {981d564524598c32f4727edbdc3ddf140734590e} }
+@gitcommit{65c44ee,
+ author = {Brent Longborough},
+ date = {2015-11-18},
+ title = {Make title a verbatim field
+Now ready for first bash at packaging and documentation
+},
+ commithash = {65c44eeae7ba3c71e80372faf322c696e6f4e102} }
+@gitcommit{201cdf1,
+ author = {Brent Longborough},
+ date = {2015-11-18},
+ title = {Merge branch 'feature/Basic.Function' into develop
+},
+ commithash = {201cdf142aa893d21eca3e23a60306c9204cd979} }
+@gitcommit{11ca996,
+ author = {Brent Longborough},
+ date = {2015-11-18},
+ title = {Initial packaging complete
+},
+ commithash = {11ca996b93ce53ad181326061f06f82f3729ad2e} }
+@gitcommit{b65bf5a,
+ author = {Brent Longborough},
+ date = {2015-11-18},
+ title = {Fix for git R.2 problem
+},
+ commithash = {b65bf5aab0851d969bc29fe5aa6216ba0bcfc278} }
+@gitcommit{63ba36f,
+ author = {Brent Longborough},
+ date = {2015-11-18},
+ title = {Tagged with gitinfo2
+},
+ commithash = {63ba36f38633c2739b594758b46e5d0166090ed3} }
+@gitcommit{9cde412,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Added makefile, new documentation file
+},
+ commithash = {9cde4128b47811cbbe8ca8271d34b8902e761836} }
+@gitcommit{afcea87,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Improve handling of gitlog bib file
+Tailor filename and suffix
+Improved defaults
+},
+ commithash = {afcea874a40df40236e6b7d99f68735e7c0ce9ee} }
+@gitcommit{4562bf2,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Change gitlog bib file defaults
+Assume nowrite for non-default bib file name
+},
+ commithash = {4562bf26a848fe10b88a720350ddfb9be7185d87} }
+@gitcommit{d798eba,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Merge branch 'feature/Refine.Options' into develop
+},
+ commithash = {d798eba144041701e562afe01d76b59ca5c8cee8} }
+@gitcommit{7ca98b4,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Tidy the (test) documents; remove local dependency
+},
+ commithash = {7ca98b436ecf1d44b6746ecf92b688432da5a1e7} }
+@gitcommit{fa237e9,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {Ensure auxfiles cleaned up before build
+},
+ commithash = {fa237e9d38bc71853c573e9f9295fe5715a25d4f} }
+@gitcommit{b4b7a78,
+ author = {Brent Longborough},
+ date = {2015-11-19},
+ title = {First published results, as a pdf
+},
+ commithash = {b4b7a7855a4814e529e60ba5e5bfce8c26e04d37} }
+@gitcommit{8aaa18d,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Implemented commit link option for Bitbucket
+},
+ commithash = {8aaa18d5413f6a35cd88bb76dc88921baebe5bfd} }
+@gitcommit{e009031,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Filling out the README
+},
+ commithash = {e009031c8b37837888a3deddc1f5838d2727e2ca} }
+@gitcommit{a9eb541,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Slight (PEBKAC) struggle with Markdown
+},
+ commithash = {a9eb541bc67a3cb8ebfd8388964c51b4aaabdbe4} }
+@gitcommit{3410e54,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {More Markdown lessons needed
+},
+ commithash = {3410e54e7164141be18a600c424131f5f66a01c8} }
+@gitcommit{03ae070,
+ author = {Brent Longborough},
+ date = {2015-11-20},
+ title = {Starting in on the documentation
+Refining Makefile
+},
+ commithash = {03ae07091187dd3ae7c6f5e136f84ac97576e352} }
+@gitcommit{f1d08b0,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Generate sample gitlog.bib outside of TeX (no write18)
+Ensure clean build
+},
+ commithash = {f1d08b0ef0a38e0f9b05c24f61490404803e9a05} }
+@gitcommit{83d3553,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Working on manual
+},
+ commithash = {83d3553a3985f07a56456da1f118f482a8748466} }
+@gitcommit{89599b6,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Finalise documentation for first release
+},
+ commithash = {89599b692692bc077a404677f62ff95cc29aa3bc} }
+@gitcommit{965b231,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Merge branch 'feature/Early.Documentation' into develop
+},
+ commithash = {965b231117452d7b3aeee1318309a6b5d24d036c} }
+@gitcommit{546f296,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Prepare for Release 0.0.beta
+},
+ commithash = {546f2962be367448568a5598d1aa563db1dc1fc7} }
+@gitcommit{34e186e,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Merge branch 'release/0.0.beta' into CTAN
+},
+ commithash = {34e186e149ed6260a62bf11fc3601a29646ce1ec} }
+@gitcommit{3b2c518,
+ author = {Brent Longborough},
+ date = {2015-11-21},
+ title = {Ensure correct file permissions (again!)
+},
+ commithash = {3b2c51811e0929696723f1f777ac0cc6ba646727} } \ No newline at end of file
diff --git a/macros/latex/contrib/gitlog/gitlog.sty b/macros/latex/contrib/gitlog/gitlog.sty
new file mode 100644
index 0000000000..6c6a527a8d
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.sty
@@ -0,0 +1,111 @@
+% gitlog.sty
+% Copyright 2015 Brent Longborough
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+% The Current Maintainer of this work is Brent Longborough.
+% -----------------------------------------------------
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{gitlog}[2015/11/22 0.0.beta typeset git change log]
+\RequirePackage{etoolbox}
+\RequirePackage{kvoptions}
+\RequirePackage[%
+ datamodel=gitlog,
+ bibstyle=gitlog,
+ sorting=none,
+ date=iso8601,
+ firstinits=true,
+ defernumbers=true,
+ backend=biber,
+]{biblatex}
+
+\SetupKeyvalOptions{family=gitlog,prefix=gitLog@}
+\DeclareBoolOption[false]{date}
+\DeclareComplementaryOption{nodate}{date}
+\DeclareStringOption[Change Log]{title}
+% write:
+\DeclareBoolOption[true]{write}
+\AddToKeyvalOption{gitlog}{write}{\def\gitLog@writeset{true}}
+% nowrite:
+\DeclareComplementaryOption{nowrite}{write}
+\AddToKeyvalOption{gitlog}{nowrite}{\def\gitLog@writeset{true}}
+% bibfile:
+\DeclareStringOption{bibfile}
+% set up github option depending on hyperref
+\@ifpackageloaded{hyperref}{%
+ \DeclareStringOption[]{github}
+ \DeclareStringOption[]{bitbucket}
+}{%
+ \DeclareVoidOption{github}{%
+ \PackageError{gitlog}{I can't generate GitHub links unless you load hyperref.}
+ }
+ \DeclareVoidOption{bitbucket}{%
+ \PackageError{gitlog}{I can't generate Bitbucket links unless you load hyperref.}
+ }
+}
+% process options:
+\ProcessKeyvalOptions{gitlog}
+% check if write/nowrite has been set:
+\ifdef\gitLog@writeset
+ {}
+ {% write/nowrite option has not been set,
+ % set boolean depending on value of \gitLog@bibfile:
+ \ifdefempty\gitLog@bibfile
+ {\booltrue{gitLog@write}}
+ {\boolfalse{gitLog@write}}%
+ }
+% set default for bibfile if necessary
+\ifdefempty\gitLog@bibfile
+ {\def\gitLog@bibfile{\jobname.gitlog.bib}}{}
+% make entrykey a link if github link requested
+\DeclareFieldFormat{entrykey}{\ttfamily[#1]}
+\@ifpackageloaded{hyperref}{%
+ \ifdefempty\gitLog@github{}{%
+ \DeclareFieldFormat{entrykey}{%
+ \href{https://github.com/\gitLog@github/commit/\thefield{commithash}}{\ttfamily[#1]}%
+ }
+ }
+ \ifdefempty\gitLog@bitbucket{}{%
+ \DeclareFieldFormat{entrykey}{%
+ \href{https://bitbucket.org/\gitLog@bitbucket/commits/\thefield{commithash}}{\ttfamily[#1]}%
+ }
+ }
+}{}
+\newcommand{\printGitLog}{%
+ \nocite{*}
+ \raggedright
+ \printbibliography[title={\gitLog@title},type=gitcommit]
+}
+\ifgitLog@date
+ \newbibmacro*{date+author}{%
+ \printtext{\\}%
+ \usebibmacro{date}%
+ \setunit*{, }%
+ \usebibmacro{author}%
+ }
+\else
+ \newbibmacro*{date+author}{%
+ \relax
+ }
+\fi
+\ifgitLog@write
+ {\catcode`\%=12
+ \immediate\write18{
+ git --no-pager log --reverse --pretty="format:@gitcommit{%h,%n
+ author = {%an},%n
+ date = {%ad},%n
+ title = {%B},%n
+ commithash = {%H}
+ }" --date=short > \gitLog@bibfile}
+ }
+\else
+ \relax
+\fi
+\addbibresource{\gitLog@bibfile}
diff --git a/macros/latex/contrib/gitlog/gitlog.tex b/macros/latex/contrib/gitlog/gitlog.tex
new file mode 100644
index 0000000000..4685c42013
--- /dev/null
+++ b/macros/latex/contrib/gitlog/gitlog.tex
@@ -0,0 +1,364 @@
+% gitlog.tex
+% Copyright 2015 Brent Longborough
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+% The Current Maintainer of this work is Brent Longborough.
+% -----------------------------------------------------
+\documentclass[a4paper,12pt,twoside,openany]{memoir}
+% =====================================================
+\usepackage[british]{babel}
+\selectlanguage{british}
+\usepackage[style=iso]{datetime2}
+\usepackage[local,pcount,grumpy,markifdirty]{gitinfo2}
+\usepackage{tgpagella}
+\usepackage{tgadventor}
+\usepackage{fontspec}
+\setmainfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Pagella}
+\setsansfont[Numbers={Proportional,OldStyle},Ligatures=TeX]{TeX Gyre Adventor}
+\setmonofont{Consolas}
+\usepackage{enumitem}
+\setlist[description]{%
+ format=\ttfamily\bfseries,
+ style=nextline,
+ leftmargin=3em,
+ itemsep=0.5\onelineskip}
+\setulmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
+\setlrmarginsandblock{0.11111\paperwidth}{0.22222\paperwidth}{*}
+\setheadfoot{1.2\baselineskip}{0.0849\paperwidth}
+\setmarginnotes{0.125\foremargin}{0.75\foremargin}{\onelineskip}
+\setheaderspaces{*}{*}{0.618}
+\checkandfixthelayout[fixed]
+% \makepagenote
+% \continuousnotenums
+% \notepageref
+% \foottopagenote
+% \renewcommand*{\printpageinnotes}[1]{%
+% (p.\pageref{#1})\space}
+% \renewcommand\printpageinnoteshyperref[1]{%
+% (p.\pageref*{#1})\space}
+% \renewcommand*{\pagenotesubhead}[3]{%
+% \subsubsection*{#1: #3}}
+\tightlists
+\chapterstyle{bringhurst}
+\pagestyle{empty}
+\aliaspagestyle{chapter}{empty}
+\settocdepth{subsection}
+\setsecnumdepth{none}
+\newcommand{\bpara}[1]{\par\vspace{\beforeparaskip}\noindent\textbf{#1}\,}
+\newcommand{\rpara}[1]{\par\noindent\textbf{#1}\,}
+\newcommand{\tcmd}[1]{\texttt{\textbackslash#1}}
+\newcommand{\dark}[1]{\texttt\textbf{{#1}}}
+\newcommand{\sfit}[1]{\textit{#1}}
+\newcommand{\git}{\sfit{git}}
+\newcommand*{\emailat}{@}
+\newcommand{\tpname}{\sfit{gitlog}}
+\newcommand{\tpfname}{\textsf{gitlog.sty}}
+% -----------------------------------------------------
+\usepackage[%
+ bookmarksnumbered,
+ bookmarksopen,
+ linktocpage,
+ ]{hyperref}
+\hypersetup{
+ pdfauthor={Brent Longborough},
+ pdftitle={The gitlog package: git change logs for LaTeX},
+ pdfkeywords={git;changelog;dvcs},
+}
+\usepackage[%
+ write,
+ bibfile=gitlog.sample.bib,
+ github=Hightor/gitlog,
+ title={Sample Git Change Log},
+]{gitlog}
+\begin{document}
+\frontmatter
+% -----------------------------------------------------
+\title{%
+ ~\\[2\baselineskip]
+ \Huge \tpfname\\[2ex]%
+ \Large A proof of concept for automatic typesetting \\of change logs from the \git\ \textsc{dvcs}
+ }
+\author{Brent Longborough}
+\date{\DTMenglishmonthname{\DTMfetchmonth{gitdate}} \DTMfetchyear{gitdate}}
+\maketitle
+
+{\centering
+Release:\gitRels\ (\gitAbbrevHash)\\
+}
+% -----------------------------------------------------
+\thispagestyle{empty}
+\aliaspagestyle{chapter}{plain}
+\clearforchapter
+\tableofcontents*
+% -----------------------------------------------------
+\mainmatter
+\pagestyle{giruled}
+\aliaspagestyle{chapter}{giplain}
+\chapter{Introduction}
+The \git{} distributed version control system
+maintains an historical log of update activity.
+The \tpname{} package provides a way automatically
+to typeset such a log, optionally linking commits
+from the typeset log
+to one of the online \textsc{dvcs} hosting services.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Limitations}
+
+The current release (\gitRel)
+is intended only as a \emph{proof-of-concept},
+and should not be used for production-level work
+unless you're happy with these limitations:
+\begin{itemize}
+\item Formatting maliciously-coded documents
+\textbf{\emph{can cause arbitrary files to be overwritten.}}
+Although this problem is easy to avoid
+(and requires the \sfit{--shell-escape} command line option),
+there are no built-in protections.
+\item The \git\ change log is built and formatted using the
+facilities of \sfit{biblatex} and \sfit{biber}.
+The way this is currently implemented makes it unlikely that
+documents using \tpname\ can contain `normal' bibliographies.
+\item New lines in the \git\ change log commit messages are
+simply converted to spaces.
+The result is pretty ugly,
+unless you've had the foresight
+to punctuate your commit messages nicely.
+\end{itemize}
+
+\noindent
+That said, I think \tpname\ will still be useful to a subset of \TeX\ users,
+and I welcome suggestions and contributed code via email or Github, where the url is
+\url{https://github.com/Hightor/gitlog/issues}.
+
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{How \tpname\ works}
+\begin{enumerate}
+\item The package uses a git command internally, via the \tcmd{write18} command,
+to write out the change log in the shape of a rather strange
+\sfit{.bib} file
+
+\item The change log .bib file contains a series of items of type \sfit{gitcommit},
+defined and formatted by the \tpname\
+data model and bibliography styles which accompany the package.
+
+\item The rest of the work is done by persuading \sfit{biblatex} and \sfit{biber}
+to treat this data as a bibliography.
+
+\item Optionally, you can generate your own `change log bibliography',
+using this command (joined up into a single line):\\[\baselineskip]
+{\ttfamily
+git --no-pager log --reverse --date=short\\
+--pretty="format:@gitcommit\{\%h,\%n author = \{\%an\},\%n\\
+date = \{\%ad\}, \%n title = \{\%B\}, \%n commithash = \{\%H\}\\
+\}" > \textit{filename}
+}
+
+\end{enumerate}
+
+% -----------------------------------------------------
+\chapter{Using the package}
+\label{ch:using}
+To collect and typeset \git{} history,
+you load the \tpname\ package in the usual way:\\[0.5\baselineskip]
+\texttt{\textbackslash usepackage[$<options>$]\{gitlog\}}
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Package options}
+
+The following options are available:
+
+\subsection{General options}
+
+\begin{description}
+
+\item[\texttt{title=\textit{log title}}]
+This option allows you to change the chapter title associated with
+the typeset change log.
+The default is `Change Log'.
+
+\item[\texttt{date}, \texttt{nodate}]
+These complementary options
+allow you to specify whether or not you want
+the author date and name to be added to the change log.
+The default is \texttt{nodate}.
+
+
+\end{description}
+
+\subsection{Options for controlling the .bib file}
+
+\begin{description}
+
+\item[\texttt{write}, \texttt{nowrite}]
+These complementary options
+allow you to specify whether or not you want
+\tpname\ to generate the special change log (\sfit{.bib})
+for you.
+
+If you specify \texttt{write}, then \tpname\ will regenerate the
+change log every time the document is formatted.
+Note that this option is implemented with the \tcmd{write18} command,
+and requires that your document be processed with the \TeX option
+\texttt{--shell-escape}.
+
+If you specify \texttt{nowrite}, then \tpname\ will not write anything,
+and the \texttt{--shell-escape} option is not required.
+However, in this case,
+you are responsible for generating the change log
+in the correct format for \tpname\ to use,
+as well as being able to hand-tailor it.
+
+If neither option is specified, the default depends on whether or not
+you use the \sfit{bibfile} option, described next.
+
+\clearpage
+\item[\texttt{bibfile=\textit{filename}}]
+The \git\ change log data is kept in
+a file in \sfit{biblatex .bib} format,
+which \tpname\ writes (if requested) and then reads
+to format the change log.
+
+If this option is not specified, then a default filename
+is used:
+\textit{<jobname>}\texttt{.gitlog.bib}.
+In this case, the default option \sfit{write} is used,
+but can be suppressed by specifying \texttt{nowrite}.
+
+This can be overridden by specifying your own choice
+of filename using this option.
+In this case, the default option \sfit{nowrite} is used,
+but you can force \tpname\ to write to your file
+by specifying \texttt{write}.
+
+\dark{Warning:} there is \emph{no} protection against writing
+to any file name whatsoever.
+The default settings are reasonably `safe';
+where you need to ship the document without its repository,
+then
+\begin{quote}
+{\ttfamily
+[write,bibfile=\jobname.local.bib]
+}
+\end{quote}
+is probably a safe set of options to use.
+
+\end{description}
+
+\subsection{Options for linking to on-line services}
+
+The change log typeset by \tpname\ can include links
+connecting each commit to its corresponding page
+in either the GitHub or the Atlassian Bitbucket
+online repository services.
+(Trade marks of their respective owners.)
+
+To use this feature, you must load the \sfit{hyperref} package
+before loading \tpname, and use one of the following,
+mutually exclusive, options.
+
+\begin{description}
+
+\item[\texttt{github=\textit{repository-path}}]
+When each commit in the changelog is typeset,
+a link is generated to the corresponding page on GitHub,
+with a \textsc{url} in this format:
+\begin{quote}
+{\ttfamily\small
+https://github.com/{\rmfamily\itshape repository-path}/commit/{\rmfamily\itshape commit-hash}
+}
+\end{quote}
+
+\item[\texttt{bitbucket=\textit{repository-path}}]
+When each commit in the changelog is typeset,
+a link is generated to the corresponding page on Atlassian Bitbucket,
+with a \textsc{url} in this format:
+\begin{quote}
+{\ttfamily\small
+https://bitbucket.org/{\rmfamily\itshape repository-path}/commits/{\rmfamily\itshape commit-hash}
+}
+\end{quote}
+
+\end{description}
+
+\section{Typesetting the change log}
+
+The command \tcmd{printGitLog}
+typesets the change log, as a new chapter containing a pseudo-bibliography,
+at that point in the document.
+At the moment, there are very few options to allow you to tailor the typography.
+
+A sample change log can be seen at the end of this manual.
+
+% -----------------------------------------------------
+\chapter{Etc}
+\section{Release notes}
+
+\rpara{R0.0.beta: 2015-11-24}
+Initial beta release
+
+\section{Acknowledgements}
+
+The \href{http://tex.stackexchange.com}{\TeX.SE community}
+has been a constant source of help, inspiration, and amazement.
+
+I'd also like to register my thanks to the owners of the packages and tools
+on which \tpname\ depends:
+biblatex, etoolbox, hyperref, and kvoptions,
+and also to
+\href{http://tex.stackexchange.com/users/35864/moewe}{moewe at \TeX.SE} for
+invaluable help during my ongoing stumblings with \sfit{biblatex}.
+
+We all depend heavily on the constant hard work
+so unstintingly given to the community by the Guardians of CTAN.
+Thank you all.
+
+The failings, of course, I claim for myself.
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{Copyright \& licence}
+Copyright \copyright\ \DTMfetchyear{gitdate}, Brent Longborough,
+who has asserted his moral right
+to be identified as the author of this work.
+
+This work --- \tpname\ --- may be distributed and/or modified under the
+conditions of the LaTeX Project Public License: either version 1.3
+of this license, or (at your option) any later version.
+
+The latest version of this license can be found
+at the \LaTeX\ Project website,%
+\footnote{(\url{http://www.latex-project.org/lppl.txt})}
+and version 1.3 or later is part of all recent distributions of
+\LaTeX.
+
+This work has the LPPL maintenance status `maintained';
+the Current Maintainer of this work is Brent Longborough.
+
+% This work consists of the files
+% gitlog.sty, gitlog.bbx, gitlog.dbx,
+% gitlog.tex, gitlog.sample.bib, gitHeadLocal.gin,
+% gitlog.pdf, and README.md
+
+% - - - - - - - - - - - - - - - - - - - - - - - - - - -
+\section{From the author}
+Although my limitations as a \TeX nician
+mean that I'm going to need a lot of expert help
+to turn \tpname\ into a delightful author experience,
+I hope you find the package useful and the concept interesting.
+I'll be very happy to receive your comments by email.\\[\baselineskip]
+Brent Longborough\\[\baselineskip]
+\textsf{brent+ctancontrib (bei) longborough (punkt) org}\\
+and at \href{http://tex.stackexchange.com/users/344/brent-longborough}{\TeX.SE}
+% -----------------------------------------------------
+\printGitLog
+% -----------------------------------------------------
+\end{document}