diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/gitlog')
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitlog/README.md | 26 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitlog/gitHeadLocal.gin | 17 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitlog/gitlog.pdf | bin | 0 -> 93972 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitlog/gitlog.sample.bib | 210 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/gitlog/gitlog.tex | 364 |
5 files changed, 617 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/gitlog/README.md b/Master/texmf-dist/doc/latex/gitlog/README.md new file mode 100644 index 00000000000..2e212d61502 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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/Master/texmf-dist/doc/latex/gitlog/gitHeadLocal.gin b/Master/texmf-dist/doc/latex/gitlog/gitHeadLocal.gin new file mode 100644 index 00000000000..b359b29e6e5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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/Master/texmf-dist/doc/latex/gitlog/gitlog.pdf b/Master/texmf-dist/doc/latex/gitlog/gitlog.pdf Binary files differnew file mode 100644 index 00000000000..7f817b5e0dd --- /dev/null +++ b/Master/texmf-dist/doc/latex/gitlog/gitlog.pdf diff --git a/Master/texmf-dist/doc/latex/gitlog/gitlog.sample.bib b/Master/texmf-dist/doc/latex/gitlog/gitlog.sample.bib new file mode 100644 index 00000000000..3deefefe7fe --- /dev/null +++ b/Master/texmf-dist/doc/latex/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/Master/texmf-dist/doc/latex/gitlog/gitlog.tex b/Master/texmf-dist/doc/latex/gitlog/gitlog.tex new file mode 100644 index 00000000000..4685c420130 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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} |