Re: [Groff] Introduction to groff in french

[Bertrand Garrigues]

Hi Gregoire,

Just read your introduction, good work!

On Tue, Oct 21 2014 at 11:01:40 PM, Peter Schaffter <address@hidden> 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