Progress

Kasper B. Graversen

     kbg@kadnet.dk

v1.10, 29.06.2003

Abstract

Progress is a package which when compiling L^{A}TEX documents, generates a HTML file giving an overview of the documents state (of how finished its parts are).

1 Version history

29.06-2003 v1.10 ∘ Enabled graphical output

∘ New options textonly, textgfx
∘ New commands \ProgressGfxXSize,
\ProgressGfxYSize \ProgressDocOutput

11.06-2003 v1.00 ∘ Improved documentation (this document)

∘ Added \ProgressReportName command to control report filename. ∘ Small bugfix.

03.05-2003 v0.80 ∘ Initial release

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 ;-)

2 Introduction

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.

3 Usage

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.

chapter For this you must use either of these options chapter, section, subsection,

section
subsection

or subsubsection. If you are using the “article” documentclass, the progress

subsubsection

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

draft print. For this you must use either of these arguments draft or final. If you

final

use the 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

textonly the document. Should it be graphical, textural or both. Option textonly gives textgfx a textural representation. Option textgfx gives a a graphical progress bar

and textural representation. Finally not specifying anything gives a graphical progress bar.

An example usage:

   \usepackage[subsubsection, draft]{progress}

Which denotes to include all levels for the overview, and a graphical bar shown in the margin denoting the progress.

\progress Throughout the document use \progress{n} after each \chapter, \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.

< 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

4 Customizations issues

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’.

4.1 Customizing progress output filename

You can customize the name of the HTML progress report, by changing the

\ProgressReportName definition of \ProgressReportName.
The default definition is: “\jobname\YYYYMMDDdate.html”

which when compiling the file “foo.tex” on 14th July 2003, the resulting filename is “foo20030714.html”. You can use any macro you want, but the most obvious ones are:

\jobname returns the name of the file being compiled by L^{A}TEX.

\YYYYMMDDdate \YYYYMMDDdate results in the current date of the form “YearMonthDay”. There \DDMMYYYYdate are 3 different date formats defined in the package: \YYYYMMDDdate, \DDMMYYYYdate

\MMDDYYYYdate  and \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

   \renewcommand{\ProgressReportName}{\jobname.html}

4.2 Customizing textural output in dvi/pdf file

You can change what is being written in the report, when a \progress is met.

\ProgressDocOutput This is done by changing the command \ProgressDocOutput. The command

takes as argument a number, denoting the percentage complete. If you want to

\ProgressDrawBar mix text and a graphical progress bar, the command \ProgressDrawBar{55} draws a bar, where 55 is the argument to the command. An example of a text-only re-definition is

   \renewcommand{\ProgressDocOutput}[1]{\marginpar{progress is #1\%}}

4.3 Customizing graphic progress bar size

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

\ProgressGfxXSize the bar can be changed by changing the values of \ProgressGfxXSize and \ProgressGfxYSize \ProgressGfxYSize. The definitions used for this document is

\renewcommand{\ProgressDocOutput}[1]{%
    \vskip-0.6cm\ProgressDrawBar{#1}\vskip 0.4cm}
\ProgressGfxXSize = 1725
\ProgressGfxYSize =   12

5 Compability issues

The package works by redefining the \chapter, \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.

6 Thanks

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 L^{A}TEX alive (be it package writers or people who introduce this wonderful world to other people).

7 Example document

For the inexperienced user, here is a example document, which shows you how to use the progress package

\documentclass{report}
\usepackage[draft,subsubsection]{progress}
\begin{document}
\chapter{foo}
\progress{29}
...
\section{bar}
\progress{33}
...
\end{document}