Re: [DotGNU]The C# Book - The plan

[S11001001]

Peter Minten wrote:
> at the moment there is still a lot unclear about the book, these issues
> are still open:
>
> * Texinfo or LaTex. Texinfo has the advantage of being a GNU standard,
> but it has been told that LaTex produces better PDF output. Of course we
> could also use Docbook or LinuxDoc. I suggest we decide this matter by
> democratic voting.

Ah, now that stuff about better PDF output is just silly. It all goes 
through TeX anyway.

Texinfo is an easier-to-use format than those others, doesn't have the 
bloat of DocBook, and generates nice output variety.

I have a copy of the Texinfo manual from 4.0 on my bookshelf, and 
reading it made everything easy. It is an excellent reference I use 
every time I write Texinfo. However, I suggest that anyone reading this 
have a look at the features introduced since, such as @copying, which 
the writers of the book should definitely use and require makeinfo >= 
4.1, like GCC.

> * The location of the files. Do we create yet another savannah project
> or do we put the file into an existing project and if so in which
> project?

YASP, or Gopal's dotgnu-doc folder.

> * Title of book.

Whatever it be, don't say "C#" in the title. The focus should be DotGNU 
and Portable .NET, not the language. The language is secondary. i.e.,

The language used in writing pnet programs is called @dfn{C#}. It is a 
new language created specifically for webservices, and standardized by 
the @address@hidden European Computer Manufacturers' 
Association has standardized C# as @uref{http://ecma.ch/forgot/the/Url, 
ECMA-33[45]? (TODO)}.}  In chapters 2, 3, 4, and 5, we will teach you 
the basics of writing programs in the C# language. We will also show you 
how to put these programs into a @dfn{build system}, which will compile 
your program source files with @command{cscc} into programs that you can 
run.

(TODO: also explanations of compilation, @dots{})

> * Division of work.

Why bother? Just say "any1 who wants to write something, write it and 
submit to Savannah patch control"

> * Writing style (how to mark important stuff, how much illustrations are
> used, etc).

Most output (i.e. Terminal) could just be showed in @smallexample 
blocks. Texinfo includes commands to `mark important stuff'. See node 
`Glyphs' (type `gGlyphs') in the texinfo manual (`info texinfo').

`illustrations' is a vague term. If you mean `examples', then I would 
like to see one per node (new concept). If you mean `pictures', then as 
little as possible (maybe some logos, showing GUI programming...)

> * A detailed listing of all the chapters to serve as a map of what needs
> to be done.

That would be a useful part of the manual itself, perhaps as the 
introduction. Then as the chapters' purposes change, you can update that 
node.

> * Things I haven't though of yet.

Cannibalize! There are two other Free programming-intro manuals I know 
of, the GNU C Tutorial Book 1 
(http://savannah.gnu.org/projects/ctut-mb-rwhe), and Introduction to 
Programming in Emacs Lisp (don't have a URL, but it *has* been published 
in book form by FSF, so shouldn't be too hard to find).

> * Explain important concepts in special paragraphs.

Hm, just put a @strong{Important!}: before the para ;)

--
Stephen Compall
DotGNU `Contributor' -- http://www.dotgnu.org

This societal shift is letting users take back control of their
futures. Just as the Magna Carta gave rights to British subjects, the
GPL enforces consumer rights and freedoms on behalf of the users of
computer software.
        -- Evan Leibovitch, "Who's Afraid of Big Bad Wolves"