[darcs-devel] darcs patch: (mostly TeXnical) changes to the documentation

David Roundy droundy at abridgegame.org
Sat Sep 17 04:48:33 PDT 2005


On Fri, Sep 16, 2005 at 05:48:13PM +0200, Andres Loeh wrote:
> Hi there.

Hello,

> I have been trying to go through the documentation and improve
> a few things on the technical side. In other words, I've tried
> to improve the TeX a bit and not break the HTML conversion at
> the same time. I'm not sure I have succeeded.

Sounds great!

> Here are the things I've been trying to do, in a not very
> systematic way:
> 
> * remove deprecated font selection commands such as \tt and \em

Just curious.  How are these deprecated? Or when? I definitely prefer \emph
over \em anyways.  As a related question, what is this \path command you're
using? Which package defines it? (I've never heard of it before...)  How is
one supposed to acheive the \tt font change? I don't know of another
command to do that, except for using verbatim which is a big stick that
breaks fragile environments...

> * remove explicit insertions of space (\hspace) or linebreaks (\\)

Okay.

> * put many expressions into typewriter font (things like
>   environment variables, command names)

Sounds good.

> * fix quoting ("foo" -> ``foo''), or remove quoting where not
>   necessary

Definitely a good thing.

> * change the way the options lists are generated

I didn't take a careful look at this, but it could be a good thing.

> * change the way verbatim environments are formatted

Same as above.  Could be good, but it's a rather large patch to digest.

> * fix some obvious typos

Obviously good.

> However, all this is only a start. There are many more things
> I'd like to do, but there is no common standard throughout the
> docs, and I'd like to do things in such a way that they are
> really seen as an improvement.

> I have some questions, too:
> 
> * Are there any stylistic guidelines for the documentation?
>   How should environment variables be formatted? How should
>   URL's be formatted? What about e-mail-addresses? What sort
>   of shell prompt should be used? (% and $ both seem to be in
>   use in different parts of the doc, but I'm not certain whether
>   that's related to root/non-root commands)

Indeed.  It started out as just my normal latex style, but has morphed, and
a lot is written by contributors with little latex experience.  And new
features got added incrementally.  A "typsetting conventions" chapter at
the beginning (or end?) as technical books sometimes have might serve a
good double-purpose of explaining the meaning of font choice to users, and
giving docs contributors a way of seeing how to format things properly.

I don't have a strong opinion on URL or email address formatting.  You
could define commands for them so we could always change our mind later.

I think so far the shell prompt is probably mostly arbitrary, but using
different prompts for root and non-root seems like a good idea.  Or one
could use # for root...  :) Actually, I am thinking that probably $ isn't a
good choice, since it can be mistaken for part of an environment variable.
So I'd lean towards either % always or % for non-root and # for root.  I
think that % is conventional for csh while $ is conventional for a bourne
shell prompt?  I don't know.

But perhaps a shell environment that adds the prompt for you would be the
best idea.  (Although that would require verbatim package hackery beyond my
skill level...)

> * For the LaTeX version, what sorts of packages can be included?
>   Does it have to be possible to compile it with any ages-old
>   LaTeX-installation? The configure script certainly doesn't check
>   whether the LaTeX installation is sufficient.

Hmmm.  Adding configure checks on the latex installation does sound like a
good idea.  I definitely don't want to require "extra" packages to be
installed by users, but anything that's included in the default tetex
package which is in debian stable would probably be fine to use.  My
practical criterion for "ancient" is something that's older than debian
stable--usually it's a pretty good definition.

I see that in your patch you do some latex "if" trickery.  That sounds like
a good idea, if it allows us to work without a package if it's not
available.  On the other hand, if one can work without a package, one
wonders why one need use it in the first place...

Do you have autoconf experience? Would you *want* to add checks for latex
packages?

> * I can see that preproc.hs is useful for the auto-generation
>   of the option lists. However, many of the other things it does
>   seem like they could be done easier/cleaner within the TeX
>   document. One example: By removing \usepackage{html} when the
>   document is not processed by latex2html, the possibility to
>   hide commands from latex2html on the TeX level is lost. On the
>   other hand, for the HTML processing that file does not even
>   seem to be required (and it's included using an illegal
>   \package instead of \usepackage then, anyway), so why is this
>   part there?

I don't quite recall why it was there.  I do recall that I added the hack
to remove it to make sure that the docs could be compiled if latex2html
isn't available.  The html package is included with latex2html, so for
users who don't have latex2html, they can't include the html package.

> * Related: preprocessing darcs for HTML currently produces a
>   file darcs.tex that cannot be processed by TeX (this is still
>   the case, I haven't fixed that yet). As a consequence, there's
>   no .aux file available for latex2html, which means that you
>   don't get section numbers when pointing to other parts of the
>   document ...

Hmmm.  Although I like latex very much, I dislike working on this sort of
business (specifically, formatting and making latex2html produce decent
html output).

> I could really use more information and feedback on what I should do and
> how it should be done (or whether this effort is welcome at all).
> 
> The patch attached contains all the changes I've made so far.  I do not
> expect this to be applied immediately, it's meant as a basis for
> discussion. I can try to make different patches out of it and resubmit in
> parts, if that's desired.

As Tommy said, smaller patches will definitely be better.  But rather than
breaking up simply by file, I think I'd prefer that patches be broken
according to change.  For example, using \path instead of \verb on all
paths could be a separate change.  This would make it easier to review the
patches, since one could just glance at the pretty trivial changes.

I wouldn't worry *too* much about patch dependencies, as long as you're
only touching the latex docs (rather than the haskell code--to modify
strings and stuff), since most "code" patches don't touch the docs.  So I
wouldn't necesarily break patches up on file boundaries.

Definitely, if your patches aren't going to commute, put any potentially
controversial ones last, so we can apply the safe ones easily.  And include
typo fixes as separate patches, so we can review them.  I'd like formatting
or cleanup patches to modify nothing else, so we don't need to review them
for correctness.

And thanks again for volunteering for this effort.  And don't let me
discourage you if I ask for too much.  I always prefer to ask for whatever
would be best, but if you run out of time, energy or interest, just say
so.  I certainly would get tired of working on docs if I were you, so I'll
fully understand.
-- 
David Roundy
http://www.darcs.net




More information about the darcs-devel mailing list