Re: notes about make docs p 3.5

[dima.pasechnik]

On Thu, Dec 03, 2020 at 03:04:28PM +0300, Dmitry wrote:
> > > It'll be very good to have some examples with explanations in the docs.
> > Maybe so.  Concrete suggestions are easy to discuss, like:
> 
> I think this example would saved me a lot of time.
> make -f mkfile
> content of mkfile:
> 
> all:
>         @echo total $(MAKE_RESTARTS) MAKE_RESTARTS
> 
> mkfile: force
>         [ x$(MAKE_RESTARTS) = x3 ] || touch mkfile ; sleep 1
> 
> force: ;
> 
> 
> > > 1) make starts with a clean slate-> make starts with a clean sTate
> > The "clean slate" idiom seems more natural to this native English speaker.  
> > Would "starts from scratch" present the same problem?
> 
> I'm sure that most people read documentation not for English
> improvement, but just to understand how things work.
> So for me (and I bet  for thousands others ) it'll be better if
> documentation would be written as simple as possible.
> What about "clean slate"  thank you, my English is a little better now.

Yes, I graduated from a high school in
Moscow in 1980 without knowing what "clean slate" means, but I learned
there much more useful "collective farm", "socialist competition", etc :-)
And for a while I needed a dictionary to read messages of the Fortran IV 
compiler
and DOS (no, not the MSDOS, there was another DOS then) on a Soviet clone of 
IBM OS 360.

With all respect, yours is is a baseless complaint - please complain to your
English teacher instead.

Cheers,
Dmitrii

> 
> 
> > > In this discussion, the man says that this is no longer relevant.
> > Perhaps we could agree that SCCS and RCS are now a minority interest.  It 
> > does seem unlikely that other systems will get similar support added to the 
> > default rules, in which case the documentation could mention SCCS and RCS 
> > specifically without becoming a maintenance burden.  Reading the original 
> > discussion, though, perhaps the more useful clarification would have been 
> > to make it explicit that Make has default, built-in make rules, the ones 
> > from https://www.gnu.org/software/make/manual/make.html#Catalogue-of-Rules.
> 
> Sorry, perhaps I don't exactly understand last sequence, but if I
> understand right - you say about adding a link to
> https://www.gnu.org/software/make/manual/make.html#Catalogue-of-Rules
> For me  (as a  nube in make) would be good something like this:
> Automatic creation of makefile currently possible from only RCS / SCCS
> systems ( more about "Built-In Rules" here -
> https://www.gnu.org/software/make/manual/make.html#Catalogue-of-Rules ).
> 
> On Tue, Dec 1, 2020 at 4:39 AM Martin Dorey
> <Martin.Dorey@hitachivantara.com> wrote:
> >
> > > It'l be very good to have some examples with explanations in the docs.
> >
> > Maybe so.  Concrete suggestions are easy to discuss, like:
> >
> > > 1) make starts with a clean slate-> make starts with a clean sTate
> >
> > The "clean slate" idiom seems more natural to this native English speaker.  
> > Would "starts from scratch" present the same problem?
> >
> > > In this discussion, the man says that this is no longer relevant.
> >
> > Perhaps we could agree that SCCS and RCS are now a minority interest.  It 
> > does seem unlikely that other systems will get similar support added to the 
> > default rules, in which case the documentation could mention SCCS and RCS 
> > specifically without becoming a maintenance burden.  Reading the original 
> > discussion, though, perhaps the more useful clarification would have been 
> > to make it explicit that Make has default, built-in make rules, the ones 
> > from https://www.gnu.org/software/make/manual/make.html#Catalogue-of-Rules.
> >
> > ________________________________
> > From: Bug-make <bug-make-bounces+martin.dorey=hds.com@gnu.org> on behalf of 
> > Dmitry <dmitry1976@gmail.com>
> > Sent: Monday, November 30, 2020 09:51
> > To: bug-make@gnu.org <bug-make@gnu.org>
> > Subject: notes about make docs p 3.5
> >
> > ***** EXTERNAL EMAIL *****
> >
> > Hello, I'm reading GNU make docs and had troubles with understanding
> > paragraph 3.5 .
> > These are some problems which I encountered:
> >
> > 1) make starts with a clean slate-> make starts with a clean sTate
> >
> > 2) It was difficult to understand how make remade makefiles without 
> > examples.
> > There is discussion when peoples explain me what's going on.
> > It'l be very good to have some examples with explanations in the docs.
> >
> > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fstackoverflow.com%2Fquestions%2F65058553%2Fhow-makefiles-are-remade-dont-understand-official-documentation%2F65061327&amp;data=04%7C01%7CMartin.Dorey%40hitachivantara.com%7C83dec436f92a4006439808d8955fbc5b%7C18791e1761594f52a8d4de814ca8284a%7C0%7C0%7C637423585715337014%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=nneTzpEm8zVuu9UnGX4%2BRfNkCNiErdp95JnClTNLfLM%3D&amp;reserved=0
> >
> > 3) It's absolutely unclear  this clause
> >
> > > If you do not specify any makefiles to be read with ‘-f’ or ‘--file’ 
> > > options, make will try the default makefile names; see What Name to Give 
> > > Your Makefile. Unlike makefiles explicitly requested with ‘-f’ or 
> > > ‘--file’ options, make is not certain that these makefiles should exist. 
> > > However, if a default makefile does not exist but can be created by 
> > > running make rules, you probably want the rules to be run so that the 
> > > makefile can be used.
> >
> > In this discussion, the man says that this is no longer relevant.
> > Perhaps it must be deleted or some explanations must be added.
> >
> > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fstackoverflow.com%2Fquestions%2F65071351%2Fegg-and-chicken-problem-when-auto-generate-default-makefile%2F65072730&amp;data=04%7C01%7CMartin.Dorey%40hitachivantara.com%7C83dec436f92a4006439808d8955fbc5b%7C18791e1761594f52a8d4de814ca8284a%7C0%7C0%7C637423585715337014%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=bL4YGGM3AiNlMG211B75ZtJ8dLrMMzWKD6HXvW0hSRA%3D&amp;reserved=0
> >
> > Respect,
> > --
> >   Dmitry
> >
> 
> 
> -- 
> --
>   Dmitry
>