Re: ada/5907: The Ada front end lacks a proper manual

Re: ada/5907: The Ada front end lacks a proper manual

[bosch]

Synopsis: The Ada front end lacks a proper manual

State-Changed-From-To: open->closed
State-Changed-By: bosch
State-Changed-When: Sat Oct  5 16:38:18 2002
State-Changed-Why:
    Manual is now included, gnat_ug.texi.

http://gcc.gnu.org/cgi-bin/gnatsweb.pl?cmd=view%20audit-trail&database=gcc&pr=5907

Re: ada/5907: The Ada front end lacks a proper manual

[Joseph S. Myers]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: <bosch@gcc.gnu.org>,  <fw@deneb.enyo.de>,  <gcc-bugs@gcc.gnu.org>, 
     <gcc-gnats@gcc.gnu.org>
Cc:  
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 6 Oct 2002 10:17:34 +0100 (BST)

 On 5 Oct 2002 bosch@gcc.gnu.org wrote:
 
 >     Manual is now included, gnat_ug.texi.
 
 It is, however, not particularly visible to users, since it lacks an info
 directory entry.
 
 -- 
 Joseph S. Myers
 jsm28@cam.ac.uk
 

Re: ada/5907: The Ada front end lacks a proper manual

[Florian Weimer]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: Florian Weimer <fw@deneb.enyo.de>
To: "Joseph S. Myers" <jsm28@cam.ac.uk>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>,  <brosgol@gnat.com>
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 20:28:59 +0100

 "Joseph S. Myers" <jsm28@cam.ac.uk> writes:
 
 > On Sun, 10 Mar 2002, Florian Weimer wrote:
 >
 >> We would need a couple of hundered macros, I think.  For example, the
 >> preprocessing rewrites all strings like "hello.adb" to "HELLO.ADB",
 >> "hello.o" to "HELLO.OBJ", and so on.  If you had to write
 >> "@helloadb{}" and "@helloo{}", reading the sources would become rather
 >> difficult.
 >
 > Define a macro that's used like @vmsfile{hello.adb}{HELLO.ADB}.
 
 This still reduces readability to a certain extent.  In addition,
 there are about 100 command names and options which have to be
 replaced in the VMS version.  Of course, you could use the macro
 approach for this one, too, but we decided not to do that.
 
 Anyway, when I've finished writing the preprocessor, I can tweak it so
 that it writes a macroized Texinfo version, and we can still decide if
 we want to use this one, or the keep the preprocessor.
 

Re: ada/5907: The Ada front end lacks a proper manual

[Joseph S. Myers]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: Florian Weimer <fw@deneb.enyo.de>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>,  <brosgol@gnat.com>
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 18:59:53 +0000 (GMT)

 On Sun, 10 Mar 2002, Florian Weimer wrote:
 
 > We would need a couple of hundered macros, I think.  For example, the
 > preprocessing rewrites all strings like "hello.adb" to "HELLO.ADB",
 > "hello.o" to "HELLO.OBJ", and so on.  If you had to write
 > "@helloadb{}" and "@helloo{}", reading the sources would become rather
 > difficult.
 
 Define a macro that's used like @vmsfile{hello.adb}{HELLO.ADB}.
 
 -- 
 Joseph S. Myers
 jsm28@cam.ac.uk
 

Re: ada/5907: The Ada front end lacks a proper manual

[Florian Weimer]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: Florian Weimer <fw@deneb.enyo.de>
To: "Joseph S. Myers" <jsm28@cam.ac.uk>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>,  <brosgol@gnat.com>
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 15:14:48 +0100

 "Joseph S. Myers" <jsm28@cam.ac.uk> writes:
 
 > On Sun, 10 Mar 2002, Florian Weimer wrote:
 >
 >> The VMS version requires substantial postprocessing (words are
 >> replaced globally, file names are rewritten).  It is not possible to
 >> express this in Texinfo.
 >
 > Why not?  If the standard manual needs the word "foo", where the VMS 
 > manual needs "bar", why shouldn't a macro @foo{} (with different 
 > definitions in the two cases) work?
 
 We would need a couple of hundered macros, I think.  For example, the
 preprocessing rewrites all strings like "hello.adb" to "HELLO.ADB",
 "hello.o" to "HELLO.OBJ", and so on.  If you had to write
 "@helloadb{}" and "@helloo{}", reading the sources would become rather
 difficult.
 
 > I don't think however the VMS way of building the manual would be of
 > relevance to the FSF sources - I think having just one version, covering
 > all systems, is generally preferred for GNU manuals.  (If it were done 
 > simply by a VMS Texinfo conditional, it might still make sense not to 
 > define that conditional when building the GNU manual on VMS.)
 
 Of course, the preprocessed manual could be committed to the CVS. But
 I doubt that this is a reasonable approach.
 
 >> bit clumsy, and the TeX implementation of Texinfo doesn't handle
 >> extensive use of conditional processing and macros very well.  On the
 >
 > What are the problems?
 
 Macro expansion in index entries causes problems, and so do some kind
 of conditionals (but these problems are more related to makeinfo,
 IIRC).

Re: ada/5907: The Ada front end lacks a proper manual

[Joseph S. Myers]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: Florian Weimer <fw@deneb.enyo.de>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>,  <brosgol@gnat.com>
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 11:50:36 +0000 (GMT)

 On Sun, 10 Mar 2002, Florian Weimer wrote:
 
 > The VMS version requires substantial postprocessing (words are
 > replaced globally, file names are rewritten).  It is not possible to
 > express this in Texinfo.
 
 Why not?  If the standard manual needs the word "foo", where the VMS 
 manual needs "bar", why shouldn't a macro @foo{} (with different 
 definitions in the two cases) work?
 
 > I think it would be possible to change the manual so that you can
 > build all the other version straight from the Texinfo sources,
 > but this might reduce maintainability.  There would be two rather
 > different ways to build the manual, the Texinfo markup would be a
 
 I don't think however the VMS way of building the manual would be of
 relevance to the FSF sources - I think having just one version, covering
 all systems, is generally preferred for GNU manuals.  (If it were done 
 simply by a VMS Texinfo conditional, it might still make sense not to 
 define that conditional when building the GNU manual on VMS.)
 
 > bit clumsy, and the TeX implementation of Texinfo doesn't handle
 > extensive use of conditional processing and macros very well.  On the
 
 What are the problems?
 
 -- 
 Joseph S. Myers
 jsm28@cam.ac.uk
 

Re: ada/5907: The Ada front end lacks a proper manual

[Florian Weimer]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: Florian Weimer <fw@deneb.enyo.de>
To: "Joseph S. Myers" <jsm28@cam.ac.uk>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>, brosgol@gnat.com
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 12:34:50 +0100

 "Joseph S. Myers" <jsm28@cam.ac.uk> writes:
 
 > On 10 Mar 2002 fw@deneb.enyo.de wrote:
 >
 >> Add the User Guide to the tree.  Florian Weimer is working on an Ada
 >> version of the preprocessor which is required to generate proper
 >> Texinfo files.
 >
 > It is desirable if possible that preprocessing is done within Texinfo (via
 > Texinfo manuals).
 
 The VMS version requires substantial postprocessing (words are
 replaced globally, file names are rewritten).  It is not possible to
 express this in Texinfo.
 
 I think it would be possible to change the manual so that you can
 build all the other version straight from the Texinfo sources,
 but this might reduce maintainability.  There would be two rather
 different ways to build the manual, the Texinfo markup would be a
 bit clumsy, and the TeX implementation of Texinfo doesn't handle
 extensive use of conditional processing and macros very well.  On the
 other hand, having the generated sources in CVS is ugly and prone to
 problems.
 
 Ben, what do you think?

Re: ada/5907: The Ada front end lacks a proper manual

[Joseph S. Myers]

The following reply was made to PR ada/5907; it has been noted by GNATS.

From: "Joseph S. Myers" <jsm28@cam.ac.uk>
To: <fw@deneb.enyo.de>
Cc: <gcc-gnats@gcc.gnu.org>,  <gcc-bugs@gcc.gnu.org>
Subject: Re: ada/5907: The Ada front end lacks a proper manual
Date: Sun, 10 Mar 2002 11:04:20 +0000 (GMT)

 On 10 Mar 2002 fw@deneb.enyo.de wrote:
 
 > Add the User Guide to the tree.  Florian Weimer is working on an Ada
 > version of the preprocessor which is required to generate proper
 > Texinfo files.
 
 It is desirable if possible that preprocessing is done within Texinfo (via
 Texinfo manuals).  Otherwise the generated Texinfo files need to be
 checked into CVS for update_web_docs to be able to put the manuals online.
 
 -- 
 Joseph S. Myers
 jsm28@cam.ac.uk
 

ada/5907: The Ada front end lacks a proper manual

[fw]

>Number:         5907
>Category:       ada
>Synopsis:       The Ada front end lacks a proper manual
>Confidential:   no
>Severity:       serious
>Priority:       high
>Responsible:    unassigned
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Mar 10 02:06:00 PST 2002
>Closed-Date:
>Last-Modified:
>Originator:     fw@deneb.enyo.de
>Release:        3.1 20020308 (prerelease)
>Organization:
>Environment:

>Description:
The Ada front end should come with two manuals, the User Guide and the Reference manual.  Only the Reference Manual is currently in the tree, but it is not built along with other GCC manuals.

The User Guide is missing completely.
>How-To-Repeat:

>Fix:
Add the User Guide to the tree.  Florian Weimer is working on an Ada version of the preprocessor which is required to generate proper Texinfo files.

The User Guide should be added as soon as possible (even if the preprocessor is not ready yet) because there might be some issues which have to be resolved before this document can be released officially by the FSF.
>Release-Note:
>Audit-Trail:
>Unformatted: