Hi Gregoire,
Just read your introduction, good work!
On Tue, Oct 21 2014 at 11:01:40 PM, Peter Schaffter <pe...@schaffter.ca> wrote:
> On Tue, Oct 21, 2014, GregExp wrote:
>> I could take the chapter 3.1 (terminal)and 3.2 (éditeur de texte en
>> console) after the chapter 3.3 (wich describe the "normal" using of
>> groff) of even at the very end, after chapter 7, as "special using of
>> groff".
>
> That's probably the best way to deal with it. From my own
> experience of leading people through groff for the first time, I
> always begin with: "Step one, fire up a text editor." The basic
> learning flow is:
>
> - fire up a text editor (doesn't matter if it's a console or GUI interface)
> - demonstrate basic groff usage with some simple text
> - introduce command line and options
> - process the demonstration
I agree with Peter that parts 3.1 and 3.2 take a bit too much space in
your introduction. Here are a few more suggestions.
First, at the beginning (before chapter 1): I think you could briefly
explain the concept of macro packages here (without changing anything to
"5. Choisir sa boîte à outils"). As you said "Groff s'utilise donc de
manière analogue à latex", you could develop a bit further and make a
parallel between groff/mom and tex/latex, and maybe emphasizes that mom
is the simpliest package. Why insist on the macros packages and on mom?
I have two reasons (from my own experience):
- People will compare groff to tex/latex, arguing that groff ("ah, that
legacy software for man pages") has an obscure syntax and that latex
is much easier. Therefore, it could be a good idea to write a few
words on the fact that convenient macro packages exist.
- When I first used groff a few years ago, I picked 'ms' because it
seems the easiest package to learn and because I didn't know the
existence mom. Neither the groff.pdf generated from the texinfo file
nor the site (at that time) did mention mom. Later I switched to mom
and of course it was easier. I don't see any point for a complete
beginner to start with something else than mom.
Secondly, I feel that your introduction lacks a concrete, real example
that shows groff's ability to produce beautiful documents. Maybe you
could use one of the example files shipped in the groff package? If I
refer to the list of files of the Ubuntu 14.04 groff package, several
example files are installed. You could suggest the reader to
regenerate, for example, sample_docs.pdf with:
groff -m mom -Tpdf sample_docs.mom > sample_docs.pdf
or even
pdfmom sample_docs.mom > sample_docs.pdf
if you want to briefly introduce the pdfmom script (sample_docs.mom will
not need it though, if I am not mistaken there are no pdf links in it).
Regards,
--
Bertrand Garrigues
