Re: [Patch docs 1/5] Update the first section of md.texi

[Jeff Law <law at redhat dot com>]

On 01/06/15 11:55, Joseph Myers wrote:
> On Tue, 6 Jan 2015, James Greenhalgh wrote:
>
> > > -The @file{.md} file for a target machine contains a pattern for each
> > > -instruction that the target machine supports (or at least each instruction
> > > -that is worth telling the compiler about).  It may also contain comments.
> > > -A semicolon causes the rest of the line to be a comment, unless the semicolon
> > > -is inside a quoted string.
> >
> > A detailed description of the syntax of a .md file does not belong in an
> > introduction. It is a deficiency of this patch set that this text is not
> > added back elsewhere. Do you have any suggestions of where the text could
> > sensibly go?
>
> A section that describes the lexical structure and syntax of .md files?
Seems reasonable. However, is that too heavyweight?

ISTM we have, effectively 3 items.

Directives that start with an open-paren and end with their associated 
close paren.  ANything in between those parens is governed by the 
documentation for the specific directive.

Outside a directive we can lines with are empty or contain just 
whitespace.  These lines are effectively ignored.

Also outside a directive are lines that start with ';;'. From the ';;' 
to the end of line are comments and ignored.



> > > @@ -54,50 +54,60 @@ See the next chapter for information on the C header file.
> > >   @node Overview
> > >   @section Overview of How the Machine Description is Used
> > >
> > > -There are three main conversions that happen in the compiler:
> > > +There are four main conversions that happen in the compiler:
> >
> > The previous text is inaccurate.
>
> It would seem better not to give a specific number (just as we've tried to
> keep down the number of references in the web pages to a particular
> version control system).
Agreed. It's bound to get out of date as some point.


> > I prefer the text below. We lose "without regard for the RTL template or
> > operand constraints", but this is contradictory anyway, as the RTL template
> > is used when expanding a define_insn.
>
> I believe the point of "without regard for the RTL template or operand
> constraints" is that when e.g. expanding addition of two SImode values,
> the RTL template from the addsi3 pattern is inserted blindly, even if that
> RTL looks nothing like RTL for an addition; nothing looks for an (add:SI)
> pattern, or generates such RTL if it's not what the RTL for addsi3 looks
> like.
Right, but the next paragraph expands on things a bit and I think is 
sufficient that we can drop the "without regard for the RTL template". 
So perhaps take that out, but leave the "without regard for the operand 
constraints".

Jeff