Re: the character ‘%’

[Noel David Torres Taño]

On Sábado 21 Agosto 2010 10:43:11 ali hagigat escribió:
> A document should not be like a complicated puzzle! One main problem
> of make document is that it does not explain  subjects in order. When
> you read any paragraph it references some pages after or before.

There are two kinds of documentation: reference manuals and tutorials. 
Reference manuals talk in depth about every subject in a program, and are a 
help for people that alredy knows the basic usage of a program. Tutorials, on 
the other hand, explain every subject you need to learn to achieve that level 
of basic usage. Maybe you need a tutorial and are trying to use the GNU-make 
REFERENCE manual to that purpose.
> 
> When you refer to those pages, they start referring to other pages and
> it continues. It destroys concentration.

That is what reference manuals do. Each page talks about one subject, and if 
it mentions other, points to it, whether it is before or after in teh manual, 
since it does not care: a reference manual is not meant to be read from start 
to end.
> 
> It suddenly uses some complex commands without prior enough
> explanations and to get rid of explanation it starts references to
> other pages. When you study other pages you can not figure out what
> was that command at last!!

Maybe you need to read a tutorial on make first:
http://www.google.com/search?q=make+tutorial
> 
> I much appreciate the writers of such magnificent tool without charge
> and their effort for documentation but it can be written more clearly.
> There is a simple rule for it:
> 
> Each explanation has some components. An explanation is written IF AND
> ONLY IF its components have been written and explained FIRST.

That's what tutorials do. You have a bunch of them on the link I've just 
provided.
> 
> The document starts talking about RCS, SCCS files in 3.7 suddenly
> without even mentioning the importance of such files that are used for
> revision control leaving the reader amazed what are these RCS and SCCS
> files? Are their names are RCS and SCCS or these two symbols specify
> the type of file they are indicating at?!!

As per the reference manual style, they're something you supessedly already 
know or you don't care to know. If you don't already know, just don't care 
about them. They're just an example there.

Hope I've helped you to solve yourmain problem

Noel
er Envite