summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/proofread/proofread.dtx
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/proofread/proofread.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/proofread/proofread.dtx')
-rw-r--r--macros/latex/contrib/proofread/proofread.dtx536
1 files changed, 536 insertions, 0 deletions
diff --git a/macros/latex/contrib/proofread/proofread.dtx b/macros/latex/contrib/proofread/proofread.dtx
new file mode 100644
index 0000000000..76fda4d2c8
--- /dev/null
+++ b/macros/latex/contrib/proofread/proofread.dtx
@@ -0,0 +1,536 @@
+% \iffalse meta-comment
+% vim: textwidth=75
+%<*internal>
+\iffalse
+%</internal>
+%<*readme>
+|
+---------:| ---------------------------------------------------------------
+proofread:| Commands for inserting annotations
+ Author:| Wybo Dekker
+ E-mail:| wybo@dekkerdocumenten.nl
+ License:| Released under the LaTeX Project Public License v1.3c or later
+ See:| http://www.latex-project.org/lppl.txt
+
+Short description:
+The proofread package defines a few LaTeX commands that are useful
+when you proofread a latex document. These allow you to easily highlight
+text and add comments in the margin. Vim escape sequences are provided
+for inserting these LaTeX commands in the source. The package is based
+on code for a text highlighting command that was published by Antal
+Spector-Zabusky in http://tex.stackexchange.com/questions/5959. The main file,
+proofread.dtx, is self-extracting, so you can generate the style file by
+compiling proofread.dtx with pdflatex.
+%</readme>
+%<*internal>
+\fi
+\def\nameofplainTeX{plain}
+\ifx\fmtname\nameofplainTeX\else
+ \expandafter\begingroup
+\fi
+%</internal>
+%<*install>
+\input docstrip.tex
+\keepsilent
+\askforoverwritefalse
+\preamble
+---------:| ---------------------------------------------------------------
+proofread:| Commands for inserting annotations
+ Author:| Wybo Dekker
+ E-mail:| wybo@dekkerdocumenten.nl
+ License:| Released under the LaTeX Project Public License v1.3c or later
+ See:| http://www.latex-project.org/lppl.txt
+
+\endpreamble
+\postamble
+
+Copyright (C) 2017 by Wybo Dekker <wybo@dekkerdocumenten.nl>
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License (LPPL), either
+version 1.3c of this license or (at your option) any later
+version. The latest version of this license is in the file:
+
+http://www.latex-project.org/lppl.txt
+
+This work is "maintained" (as per LPPL maintenance status) by
+Wybo Dekker.
+
+This work consists of the file proofread.dtx and a Makefile.
+Running "make" generates the derived files README, proofread.pdf and
+proofread.sty.
+Running "make inst" installs the files in the user's TeX tree.
+Running "make install" installs the files in the local TeX tree.
+
+\endpostamble
+
+\usedir{tex/latex/proofread}
+\generate{
+ \file{\jobname.sty}{\from{\jobname.dtx}{package}}
+}
+%</install>
+%<install>\endbatchfile
+%<*internal>
+\usedir{source/latex/proofread}
+\generate{
+ \file{\jobname.ins}{\from{\jobname.dtx}{install}}
+}
+\nopreamble\nopostamble
+\usedir{doc/latex/proofread}
+\generate{
+ \file{README.txt}{\from{\jobname.dtx}{readme}}
+}
+\ifx\fmtname\nameofplainTeX
+ \expandafter\endbatchfile
+\else
+ \expandafter\endgroup
+\fi
+%</internal>
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{proofread.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{proofread}
+%<*package>
+ [2019/04/25 v1.04 Commands for inserting annotations]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry}
+\usepackage[numbered]{hypdoc}
+\usepackage{microtype}
+\usepackage{\jobname}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\parindent0pt\parskip2ex
+\makeatletter
+\def\com#1{\relax}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{\jobname.dtx}
+% \DoNotIndex{\AtBeginDocument, \DeclareOption, \DeclareRobustCommand,
+% \DoubleSpacing, \OnehalfSpacing, \PackageError, \ProcessOptions,
+% \RequirePackage, \advance, \baselineskip, \begin, \bgroup, \coordinate, \def,
+% \discretionary, \egroup, \else, \end, \endinput, \endpgfextra, \fi, \fill,
+% \footnotesize, \global, \hbox, \hilite, \ifdef, \ifdim, \ifx, \let, \marginpar,
+% \marginparmargin, \marginparpush, \mbox, \newbox, \newcommand, \newcount,
+% \newdimen, \newif, \p, \path, \pgfextra, \raggedright, \renewcommand, \sbox,
+% \setSpacing, \setstretch, \st, \the, \tikz, \tikzset, \undefined, \usebox,
+% \usetikzlibrary,\y,
+% }
+%
+%\title{\textsf{proofread} --- Commands for inserting annotations\thanks{This file
+% describes version \fileversion, last revised \filedate.}
+%}
+%\author{Wybo Dekker\thanks{E-mail: wybo@dekkerdocumenten.nl}}
+%\date{Released \filedate}
+%
+%\maketitle
+%
+%\changes{v1.00}{2015/09/06}{First public release}
+%\changes{v1.01}{2015/12/07}{running counter was sometimes not advanced}
+%\changes{v1.02}{2017/02/28}{- Now works in tables, footnotes, minipages and more\\
+% - package options frame, corrected, uncorrected added\\
+% - package options doublespacing, onehalfspacing added\\
+% - skp command for manual moving down marginnotes\\
+% - vim commands are provided for removing notes,\\
+% either honoring or undoing the correction.}
+%\changes{v1.03}{2018/07/31}{added warning to use xetex or luatex for non-ASCII
+% source.}
+%\changes{v1.04}{2019/04/25}{removed overstriking in the \del command, as
+% it forces the text on a single line.}
+%
+% \begin{abstract}\noindent
+% The |proofread| package defines a few \LaTeX\ commands that are useful when
+% you proofread a latex document. These allow you to easily highlight text and
+% add comments in the margin. Vim escape sequences are provided for inserting or
+% removing these \LaTeX\ commands in the source. The package is based on code
+% for a text highlighting command that was published by Antal Spector-Zabusky in
+% \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
+%
+% Options are provided for displaying the document with extra line spacing,
+% and for display of it in either uncorrected or corrected state, both
+% without margin notes.
+% \end{abstract}
+%
+% \section{Usage}
+% Note: this package is based on the |soul| package, so if you plan to
+% highlight non-ASCII characters, you must compile your source with either
+% |xetex|- or |luatex|-based compilers.
+
+% The commands described below display a highlighted phrase in your
+% compiled document and place a comment in the margin, prefixed with a
+% counter, which is indicated with |n| in the following. This
+% counter is useful in the communication with the author of the document.
+%
+% Previous versions of this package used the standard \LaTeX\ |\marginpar| to
+% create notes in the margin. However, although these will not overwrite each
+% other, they can not be used in tables, minipages, footnotes and more.
+% Therefore, this version creates margin notes using the |marginnote| package,
+% in order to make them work in tables, minipages, footnotes and more. This
+% implies that margin notes are placed at the vertical position where they are
+% called, instead of being automatically stacked. So if several notes are
+% generated on the same line, they overwrite each other. You can prevent this by
+% \DescribeMacro{skp}
+% prefixing the second note on the line with |\skp| or |\skp[1]|, the third note
+% with |\skp[2]| and so on. Multiline notes may need larger numbers.
+%
+% The following supposes that you have installed vim-facilities as
+% described in section~\ref{inst} (``Installing the Vim commands'').
+%
+% \DescribeMacro{\del}
+% |\del{phrase}| displays \del{phrase} and places |n: delete| in the
+% margin. In the |vim| editor, you can generate this code by selecting the
+% \DescribeMacro{esc d}
+% phrase and typing |<escape>d|. After typing this escape sequence, you
+% will be in normal mode, behind the closing brace.
+% \DescribeMacro{\yel}
+% |\yel[comment]{phrase}| displays \yel{phrase} and places
+% |n: comment| in the margin. In the |vim| editor, you can generate
+% \DescribeMacro{esc y}
+% this code by selecting the phrase and typing |<escape>y|.
+% After typing this escape sequence, you will be in insert mode between the
+% square bracket pair, ready to insert the \textit{comment}.
+%
+% \DescribeMacro{\add}
+% |\add{phrase}| displays \add{phrase} and places |n: add| in the
+% margin. In the |vim| editor, you can generate this code \emph{after} the
+% \DescribeMacro{esc a}
+% current cursor position by typing |<escape>a|, or \emph{before} the cursor
+% \DescribeMacro{esc i}
+% position with |<escape>i|. After typing these escape sequences, you will
+% be in insert mode between the braces pair, ready to type what should be
+% added.
+%
+% \DescribeMacro{\rep}
+% |\rep{phrase}{replacement}| displays \rep{phrase}{replacement} and places
+% |n: was: phrase| in the margin. In the |vim| editor, you can
+% \DescribeMacro{esc r}
+% generate this code by selecting the phrase and typing |<escape>r|.
+% After typing this escape sequence, you will be in insert mode between
+% the second pair of braces, ready to insert the new content.
+%
+% \DescribeMacro{\com}
+% |\com{comment}| is used by |\del|, |\yel|, |\add|, and |\rep| to place
+% |n: comment| in the margin. You can use it to place comment in the
+% margin without text highlighting. In the |vim| editor, you can insert the
+% \DescribeMacro{esc c}
+% command by typing |<escape>c|.
+% After typing this escape sequence, you will be in insert mode between the
+% braces pair, ready to type your comment.
+%
+% \DescribeMacro{\hilite}
+% |\hilite[options]{phrase}| is the command on which the above commands are
+% based. It was published by Antal Spector-Zabusky in
+% \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
+% It highlights the phrase with the default colour, yellow, using the
+% default fill opacity, 0.25; but using the options, you can change this.
+% For example,
+% \hilite[fill=blue,draw=yellow,opacity=.5,line width=3pt]{this phrase}
+% was highlighted with blue, with a 3pt width line in yellow around it,
+% with the command:
+%
+% |\hilite[fill=blue,draw=yellow,opacity=.5,line width=3pt}|
+%
+% Both the fill color and the draw color get 50\% opacity, but you can set
+% each individually with the |fill opacity| and |draw opacity| options.
+% See the documentation of the tikz package for more options.
+%
+% \section{Installing the Vim commands}\label{inst}
+% The |proofread| distribution comes with a Vimball archive named
+% |proofread.vmb|. Edit that file in vim and run the command: |:so %|. This will
+% install the necessary files in your |~/.vim| directory, plus the Ruby executable
+% |proofread| in your |~/bin| directory. The latter should be in your |PATH| of
+% course, and you'll have to set its executable flag (|chmod +x ~/bin/proofread|).
+% Finally, in order to use these facilities, you'll have to add this line
+% at the end of your Latex source: |% vim: syntax=proofread|.
+%
+% The majority of the escape commands that are installed by this
+% procedure have been described above. However, there are two others:
+% \DescribeMacro{esc u}
+% The vim sequence |<escape>u| will \emph{undo} the nearest of the three
+% letter commands (|\del, \add, \yel, \rep, \com|) described above, which
+% starts \emph{before} the current cursor position (which may be even on
+% the first character after the starting |\|). So if it sees
+% |\del{something}| it will replace that with |something|, and if it sees
+% |\add{something}| it will remove that.
+%
+% \DescribeMacro{esc h}
+% The counterpart is the |<escape>h| sequence, which will \emph{honor} the
+% first command found before the cursor. If it sees |\del{something}| it will
+% remove it, and if it sees |\add{something}| it will replace it with
+% |something|.
+% The following table illustrates what happens with these two escape
+% sequences:
+%
+% \begin{tabular}{@{}lll@{}}
+% &after |<escape>u|&after |<escape>h| \\
+% |\del{something}| & something & \\
+% |\add{something}| & &something \\
+% |\yel{something}| &something &something \\
+% |\yel[remark]{something}| &something &something \\
+% |\com{something}| & & \\
+% |\rep{old}{new}| &old &new \\
+% \end{tabular}
+%
+% As you see, both sequences simply undo |\yel| and |\com| commands, because
+% they are comments, not corrections.
+%
+% \section{Package options}
+% Options are provided, displaying the document in various spacing and
+% correction modes.
+% \DescribeMacro{onehalfspacing}
+% The |onehalfspacing| option displays the document with 1.5 times the
+% normal line spacing,
+% \DescribeMacro{doublespacing}
+% The |doublespacing| option displays the document with doubled
+% line spacing.
+% \DescribeMacro{uncorrected}
+% The |uncorrected| displays the document in its uncorrected state, without
+% notes in the margin.
+% \DescribeMacro{corrected}
+% The |corrected| displays the document in its corrected state, without
+% notes in the margin.
+% \DescribeMacro{frame}
+% Finally, the |frame| option is provided for visually handicapped users;
+% it causes .5pt black borders to be drawn around the colored backgrounds
+% around \hilite[draw=black,line width=.5pt]{marked} texts.
+%\StopEventually{^^A
+% \PrintChanges
+% \clearpage
+% \PrintIndex
+%}
+%
+% \section{Implementation}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+% Option handling:
+% For the |onehalfspacing| and |doublespacing| options we need the setspace
+% package, but the memoir class has its own version for this. So if
+% |\DoubleSpacing| is defined, we redefined the other commands needed.
+% The |PR@spaced| remembers if margin notes need a shift up.
+% \begin{macrocode}
+\RequirePackage{marginnote}
+\ifx\undefined\DoubleSpacing
+ \RequirePackage{setspace}
+\else
+ \let\setstretch\setSpacing
+ \let\onehalfspacing\OnehalfSpacing
+ \let\doublespacing\DoubleSpacing
+\fi
+\newif\ifPR@spaced\PR@spacedfalse
+\newdimen\PR@unit\PR@unit.6\baselineskip
+\DeclareOption{onehalfspacing}{\onehalfspacing\PR@spacedtrue\PR@unit.525\baselineskip}
+\DeclareOption{doublespacing}{\doublespacing\PR@spacedtrue\PR@unit.35\baselineskip}
+% \end{macrocode}
+% The default is to show corrections; the |corrected| and |uncorrected|
+% options will show the document without those in either corrected of
+% uncorrected state.
+% \begin{macrocode}
+\newif\ifPR@corrected\PR@correctedfalse
+\newif\ifPR@uncorrected\PR@uncorrectedfalse
+\DeclareOption{corrected}{\PR@correctedtrue}
+\DeclareOption{uncorrected}{\PR@uncorrectedtrue}
+% \end{macrocode}
+% The frame option draws a black 0.5pt frame around colored areas for
+% the visually disabled.
+% \begin{macrocode}
+\newif\ifPR@frame\PR@framefalse
+\newdimen\PR@lw\PR@lw=0pt
+\DeclareOption{frame}{\PR@lw=.5pt\PR@frametrue}
+\ProcessOptions
+% \end{macrocode}
+% The following code for a text highlighting command (here renamed to
+% |\hilite| was published by Antal Spector-Zabusky in
+% \href{http://tex.stackexchange.com/questions/5959}{StackExchange}.
+% \begin{macrocode}
+\RequirePackage{soul}
+\RequirePackage{tikz}
+\usetikzlibrary{calc}
+\usetikzlibrary{decorations.pathmorphing}
+
+\newcommand{\PR@defhiliter}[3][]{%
+ \tikzset{every hiliter/.style={fill=#2,fill opacity=#3, #1}}%
+}
+
+\PR@defhiliter{yellow}{.25}
+
+\newcommand{\PR@hilite@Dohilite}{
+ \fill [ decoration = {random steps, amplitude=1pt, segment length=15pt}
+ , outer sep = -15pt, inner sep = 0pt, decorate
+ , every hiliter, this hiliter ]
+ ($(begin hilite)+(0,8pt)$) rectangle ($(end hilite)+(0,-3pt)$) ;
+}
+
+\newcommand{\PR@hilite@Beginhilite}{
+ \coordinate (begin hilite) at (0,0) ;
+}
+
+\newcommand{\PR@hilite@Endhilite}{
+ \coordinate (end hilite) at (0,0) ;
+}
+
+\newdimen\PR@hilite@previous
+\newdimen\PR@hilite@current
+% \end{macrocode}
+
+% \begin{macro}{\hilite}
+% \begin{macrocode}
+\DeclareRobustCommand*\hilite[1][]{%
+ \ifPR@frame%
+ \tikzset{this hiliter/.style={#1,draw=black,line width=\PR@lw}}%
+ \else%
+ \tikzset{this hiliter/.style={#1}}%
+ \fi
+ \SOUL@setup
+ %
+ \def\SOUL@preamble{%
+ \begin{tikzpicture}[overlay, remember picture]
+ \PR@hilite@Beginhilite
+ \PR@hilite@Endhilite
+ \end{tikzpicture}%
+ }%
+ %
+ \def\SOUL@postamble{%
+ \begin{tikzpicture}[overlay, remember picture]
+ \PR@hilite@Endhilite
+ \PR@hilite@Dohilite
+ \end{tikzpicture}%
+ }%
+ %
+ \def\SOUL@everyhyphen{%
+ \discretionary{%
+ \SOUL@setkern\SOUL@hyphkern
+ \SOUL@sethyphenchar
+ \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
+ }{%
+ }{%
+ \SOUL@setkern\SOUL@charkern
+ }%
+ }%
+ %
+ \def\SOUL@everyexhyphen##1{%
+ \SOUL@setkern\SOUL@hyphkern
+ \hbox{##1}%
+ \discretionary{%
+ \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
+ }{%
+ }{%
+ \SOUL@setkern\SOUL@charkern
+ }%
+ }%
+ %
+ \def\SOUL@everysyllable{%
+ \begin{tikzpicture}[overlay, remember picture]
+ \path let \p0 = (begin hilite), \p1 = (0,0) in \pgfextra
+ \global\PR@hilite@previous=\y0
+ \global\PR@hilite@current =\y1
+ \endpgfextra (0,0) ;
+ \ifdim\PR@hilite@current < \PR@hilite@previous
+ \PR@hilite@Dohilite
+ \PR@hilite@Beginhilite
+ \fi
+ \end{tikzpicture}%
+ \the\SOUL@syllable
+ \tikz[overlay, remember picture] \PR@hilite@Endhilite ;%
+ }%
+ \SOUL@
+}
+% \end{macrocode}
+% \end{macro}
+% Reduce minimum vertical space between margin paragraphs; if the memoir
+% class is active, use the outer margin:
+% \begin{macrocode}
+\AtBeginDocument{\marginparpush2pt}
+\ifx\undefined\marginparmargin\else\marginparmargin{outer}\fi
+% \end{macrocode}
+% We need a save box and a counter for prefixing the margin paragraphs:
+% \begin{macrocode}
+\newcount\PR@markerno\PR@markerno=1
+% \end{macrocode}
+% \begin{macro}{\com}
+% Make a raggedright margin note, in footnote fontsize, prefixed with the counter
+% plus a colon:
+% \begin{macrocode}
+\newcommand{\com}[1]{%
+ \marginnote{%
+ \setstretch{1}%
+ \raggedright%
+ \footnotesize%
+ \the\PR@markerno: #1%
+ }[\PR@skip]%
+ \global\PR@skip0pt
+ \global\advance\PR@markerno1%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\skp}
+% \begin{macrocode}
+\newdimen\PR@skip\PR@skip0\PR@unit
+\newcommand{\skp}[1][1]{%
+ \PR@skip#1\PR@unit%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\del}
+% \begin{macrocode}
+\newcommand{\del}[1]{%
+ \com{delete}%
+ \hilite[red]{#1}%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\yel}
+% \begin{macrocode}
+\newcommand{\yel}[2][]{%
+ \com{#1}%
+ \hilite{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\add}
+% \begin{macrocode}
+\newcommand{\add}[1]{%
+ \com{add}%
+ \hilite[green]{#1}%
+}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\rep}
+% \begin{macrocode}
+\newcommand{\rep}[2]{%
+ \com{was: #1}%
+ \hilite[blue]{#2}%
+}
+% \end{macrocode}
+% If one of the |corrected| or |uncorrected| options is used, redefine the
+% above commands accordingly:
+% \begin{macrocode}
+\ifPR@uncorrected
+ \ifPR@corrected
+ \PackageError{proofread}{You may not use both the corrected and uncorrected options}
+ \fi
+ \def\com#1{} \def\add#1{} \def\del#1{#1} \def\rep#1#2{#1}
+ \renewcommand{\yel}[2][]{#2}\renewcommand{\hilite}[2][]{#2}
+\else
+ \ifPR@corrected
+ \def\com#1{} \def\add#1{#1} \def\del#1{} \def\rep#1#2{#2}
+ \renewcommand{\yel}[2][]{#2}\renewcommand{\hilite}[2][]{#2}
+ \fi
+\fi
+
+\endinput
+%</package>
+% \end{macrocode}
+% \end{macro}
+%\Finale