Re: Very ambiguous style of documentation and writing!

[Paul Smith]

On Wed, 2010-08-18 at 12:24 +0430, ali hagigat wrote:
> 'make' is the base of all open source projects and without
> understanding it completely, it will not be clear from what file a
> software project starts and how the instruction flow continues. But
> that base is covered with the sentences not so clear and because of
> that many can not understand and contribute to the open source
> projects.........

I'm sorry you're having a difficult time understanding the manual, but
constant whinging like this is not productive and won't get you the
answers you want.  If you have specific questions or don't understand
specific parts of the manual, feel free to ask for clarification with a
positive attitude and respect for the time people have spent to create
this software and documentation for you and help you understand it;
consider that attitude part of your payment for the help you're getting.

If you think the manual is incorrect or too unclear in specific areas,
feel free to create a Documentation bug or enhancement request on
Savannah.  I warn you that a bug saying the manual should be rewritten
will not be addressed.

If you think you could do a better job writing the manual, please feel
free!  We always encourage contributions by anyone, on any topic.  Be
aware that you'll need to place the documentation under the appropriate
licensing and assign copyright to the FSF.  Let me know if you'd like to
get the paperwork started.

> -------------------------------------------------------------------------------------------------------------------------------------------------
> 4.13 Generating Prerequisites Automatically
> To avoid this hassle, most modern C compilers can write these rules
> for you, by looking
> at the #include lines in the source files. Usually this is done with
> the ‘-M’ option to the
> compiler. For example, the command:
> cc -M main.c
> generates the output:
> main.o : main.c defs.h
> Thus you no longer have to write all those rules yourself. The
> compiler will do it for you.
> Note that such a prerequisite constitutes mentioning ‘main.o’ in a
> makefile, so it can
> never be considered an intermediate file by implicit rule search. This
> means that make won’t
> ever remove the file after using it; see Section 10.4 [Chains of
> Implicit Rules], page 107.
> -----------------------------------------------------------------------------------------------------------------------------------
> "Note that such a prerequisite constitutes mentioning ‘main.o’ in a 
> makefile..."
> What does the above sentence mean? What prerequisite is it talking
> about? Please write an example. Does it mean the hear file?

I don't know what a "hear file" is.  Anyway, you're right that this
sentence is incorrect; that should say "such a _rule_", not "such a
_prerequisite_".

> "so it can never be considered an intermediate file by implicit rule search..."
> What is "it" in the above sentence?

main.o, of course.  This is really English Grammar 101, here.

> Where is that intermediate file?

I don't understand: what do you mean "where is it"?

> make removes the file?!! How make removes files in an implicit rule
> search?

See the section that is referred to in that paragraph ("Chains of
Implicit Rules") to learn about when make removes intermediate files.
That's why we put the crossreference there.

> Where is the place of the command, cc -M main.c? is it inside a makefile?

This section just shows you the command and how it's run.  Keep reading
to see how that information is used in a makefile.

> "Note that such a prerequisite constitutes mentioning ‘main.o’ in a
> makefile, so it can
> never be considered an intermediate file by implicit rule search...."
> 
> What is the concept and function of constituting? How it is done? If
> it does not constitute so it can be considered an intermediate file?
> Can you clarify the detailed steps of making the decision to
> constitute and making an intermediate file?

This is a common English phrase: to say "A constitutes B" means that if
you have A, you also have B; B is made up of or composed of or
equivalent to A.

Another way to write this that would be equally correct (given the
correction about "rule" instead of "prerequisite" above) would be "Note
that such a rule means that 'main.o' is mentioned in the makefile, so it
can never be considered an intermediate file".

-- 
-------------------------------------------------------------------------------
 Paul D. Smith <address@hidden>          Find some GNU make tips at:
 http://www.gnu.org                      http://make.mad-scientist.net
 "Please remain calm...I may be mad, but I am a professional." --Mad Scientist