doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 199 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/progress/progress.tex b/Master/texmf-dist/doc/latex/progress/progress.tex
new file mode 100644
index 00000000000..c9c53a4103f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/progress/progress.tex
@@ -0,0 +1,199 @@
+\documentclass{article}
+\usepackage[english]{babel}
+\usepackage[T1]{fontenc}
+\usepackage[latin1]{inputenc}
+\usepackage{url}
+\usepackage[draft, subsection]{progress}
+\setlength{\parindent}{0mm}
+\setlength{\parskip}{2mm}
+\reversemarginpar
+\begin{document}
+\title{Progress}
+\author{Kasper B.\ Graversen\\\url{kbg@kadnet.dk} }
+\date{v1.10, 29.06.2003}
+\maketitle
+%\tableofcontents
+
+% shortcuts for the margin notes...
+\newcommand{\margincommanda}[1]{\marginpar{{\scriptsize \texttt{\textbackslash{}#1}}}}
+\newcommand{\margincommandb}[1]{\marginpar{{\scriptsize \texttt{#1}}}}
+
+
+% change layout of progress meters
+\renewcommand{\ProgressDocOutput}[1]{\vskip-0.6cm\ProgressDrawBar{#1}\vskip 0.4cm}
+\ProgressGfxXSize = 1725
+\ProgressGfxYSize =  12
+
+
+
+
+
+
+
+
+\begin{abstract}
+Progress is a package which when compiling \LaTeX{} documents,
+generates a HTML file giving an overview of the documents state (of how finished its parts are).
+\end{abstract}
+
+
+\section{Version history}
+\progress{10}
+\begin{tabular}{llp{8.4cm}}
+29.06-2003  & v1.10 & $\circ$ Enabled graphical output \\
+            &       & $\circ$ New options \texttt{textonly}, \texttt{textgfx}    \\
+            &       & $\circ$ New commands \verb|\ProgressGfxXSize|, \par \verb|\ProgressGfxYSize| \verb|\ProgressDocOutput|    \\
+\\
+11.06-2003  & v1.00 & $\circ$ Improved documentation (this document)  \\
+			&		& $\circ$ Added \verb|\ProgressReportName| command to control report filename.\\
+			&		& $\circ$ Small bugfix.\\
+\\
+03.05-2003 	& v0.80 & $\circ$ Initial release \\
+\end{tabular}
+
+\bigskip
+If you enjoy using this package, please write me an email stating so. It's always nice to know someone is using your work, and it'll probably encourage me to keep updating the package \verb|;-)|
+
+
+
+\section{Introduction}
+\progress{20}
+When working on larger documents, or in collaboration with other people, it's nice to have an overview of the documents' state.  By inserting progress estimates throughout the document, this package is able to generate a HTML file which gives such an overview. Additionally the package enables you to include the estimates in the document, so   readers are aware of the state of what they are reading.
+
+
+\section{Usage}
+\progress{30}
+In the top of you document you must determine how detailed you want the overview. It can be compared to the table of contents list, where you can determine its verbosity. You have to choose whether you want to see only chapters, chapters--sections, chapters--subsections or chapters--subsubsections. For this you must use either of these options \margincommandb{chapter}\texttt{chapter}, \margincommandb{section}\texttt{section}, \margincommandb{subsection}\texttt{subsection}, or \margincommandb{subsubsection}\texttt{subsubsection}. If you are using the ``article'' documentclass, the progress adapts to the fact, that chapters do not exist.
+
+Secondly, you must choose whether the document is a draft (progress estimates are included in the document), or whether the document is ready for the final print. For this you must use either of these arguments\margincommandb{draft} \texttt{draft} or \texttt{final}. If \margincommandb{final} you use the \texttt{final} option, no progress estimates are included in the document, and no progress report is generated.
+
+Thirdly, you must choose the output of the ``progress information'' inserted into the document. Should it be graphical, textural or both.  Option \margincommandb{textonly} \texttt{textonly} gives a textural representation. Option \margincommandb{textgfx} \texttt{textgfx} gives a a graphical progress bar and textural representation. Finally not specifying anything gives a graphical progress bar.
+
+\bigskip
+An example usage:\\
+\verb|   \usepackage[subsubsection, draft]{progress}|
+\vskip 0.3cm
+Which denotes to include all levels for the overview, and a graphical bar shown in the margin denoting the progress.
+
+Throughout \margincommanda{progress} the document use \verb|\progress{|$n$\verb|}| after each \textbackslash\texttt{chapter}, \textbackslash\texttt{section},... where $n$ is a number between $-100$ to $100$. Use the numbers $-100$ to $-1$ to denote severe problems has been encountered (see the table below).
+
+The meaning of this number is described in the generated HTML file and below. You can easily change the meaning by hacking the sty file.
+
+\medskip
+
+\begin{tabular}{rp{10cm}}
+\hline
+$<$ 0  & Means the same as above 0, but indicate that the author is stuck and needs consultance with co-author(s)\\
+$0-50$ & Unfinished\\
+$51-70$& 1st draft - can have ``rough edges''\\
+       & Focus: main form, contents, major points.\\
+$71-80$& 2nd draft.\\
+       & Focus: section consistency internally within the chapter, errors, misunderstandings, disagreements, missing points, missing references, additions, readability.\\
+$81-90$& 3rd draft\\
+       & Focus: chapter consistency externally within the report, agreement with contents, form, last check if points have been left out, readability.\\
+$91-99$& Deliverable.\\
+95 	    & Deliverable, all quotes checked.\\
+96 	    & Deliverable, BibTeX references checked.\\
+97 	    & Deliverable, punctuation checked.\\
+98 	    & Deliverable, thesaurus consulted.\\
+99 	    & Deliverable, whole document spelling checked.\\
+100     & Finished\\
+\hline
+\end{tabular}
+
+
+\section{Customizations issues}
+\progress{40}
+We have now shown the general usage. More advanced users probably would like a bit more control, thus below, we present various aspects of customizing the effects of `progress'.
+
+\subsection{Customizing progress output filename}
+\progress{50}
+You can customize the name of the HTML progress report, by changing the definition of \margincommanda{ProgressReportName} \verb|\ProgressReportName|.
+
+\medskip
+The default definition is:  ``\verb|\jobname\YYYYMMDDdate.html|''
+
+
+
+which when compiling the file ``foo.tex'' on \today{}, the resulting filename is ``foo\YYYYMMDDdate .html''. You can use any macro you want, but the most obvious ones are:
+
+\verb|\jobname| returns the name of the file being compiled by \LaTeX{}.
+
+\verb|\YYYYMMDDdate|\margincommanda{YYYYMMDDdate} results in the current date of the form ``YearMonthDay''. There are 3 different date formats defined in the package:
+\verb|\YYYYMMDDdate|,
+\verb|\DDMMYYYYdate|\margincommanda{DDMMYYYYdate}
+and \verb|\MMDDYYYYdate|\margincommanda{MMDDYYYYdate}
+
+If you prefer to have only one progress file you can change the output file to not contain any dates, hence it will always overwrite the old progress report file. This is easily done by inserting
+
+\verb|   \renewcommand{\ProgressReportName}{\jobname.html}|
+
+
+
+\subsection{Customizing textural output in dvi/pdf file}
+\progress{60}
+You can change what is being written in the report, when a \verb|\progress| is met. This is done by changing the command \margincommanda{ProgressDocOutput} \verb|\ProgressDocOutput|. The command takes as argument a number, denoting the percentage complete.
+If you want to mix text and a graphical progress bar, the command \margincommanda{ProgressDrawBar} \verb|\ProgressDrawBar{55}| draws a bar, where 55 is the argument to the command. An example of a text-only re-definition is
+
+\verb|   \renewcommand{\ProgressDocOutput}[1]{\marginpar{progress is #1\%}}|
+
+
+
+
+
+
+
+
+\subsection{Customizing graphic progress bar size}
+\progress{70}
+The graphical progress bars' size can be changed. In this document, I have experimented, by letting the progress bar be as wide as the textlines, which gives another effect than having a small gauge in the margin. The size of the bar can be changed by changing the values of \margincommanda{ProgressGfxXSize } \verb|\ProgressGfxXSize|  and \margincommanda{ProgressGfxYSize} \verb|\ProgressGfxYSize|.
+The definitions used for this document is
+
+\begin{verbatim}
+\renewcommand{\ProgressDocOutput}[1]{%
+    \vskip-0.6cm\ProgressDrawBar{#1}\vskip 0.4cm}
+\ProgressGfxXSize = 1725
+\ProgressGfxYSize =   12
+\end{verbatim}
+
+
+
+
+
+\section{Compability issues}
+\progress{80}
+
+The package works by redefining the \verb|\chapter|,  \verb|\section|, etc. commands, so when encountered, information will be written in the HTML file. For this reason, this package does not work with \TeX{} documents, or `exotic' extensions, as they do not define such commands. I have tested the package only with the ``book'', ``report'', and ``article'' documentstyles, and they worked fine. Further I've tested progress with the package `hitec', which is an altered ``article'' cls which also worked fine.
+
+
+
+\section{Thanks}
+\progress{90}
+
+Thanks to Robin Fairbairns for helping me sorting things out ;-)
+
+Thanks to Dan Luecking for some definitions
+
+Also thanks to David Bausum for his free 'trept' ``\TeX{}: Reference and Examples'' information material.
+
+And finally, thanks to everyone keeping \LaTeX{} alive (be it package writers or people who introduce this wonderful world to other people).
+
+
+\section{Example document}
+\progress{100}
+For the inexperienced user, here is a example document, which shows you how to use the progress package
+
+\begin{verbatim}
+\documentclass{report}
+\usepackage[draft,subsubsection]{progress}
+\begin{document}
+\chapter{foo}
+\progress{29}
+...
+\section{bar}
+\progress{33}
+...
+\end{document}
+\end{verbatim}
+\end{document}
+