Re: [Ada] User Guide?

Re: [Ada] User Guide?

[dewar]

<<I think this should be achievable with the approach we have in mind for
the users guide. We will take care of the minor issues for gnat_rm.texi.
>>

Just so no one is confused, we are coordinated with Florian here, and 
"the approach we have in mind" is exactly the approach that Florian has
been persuing (at least that's my understanding, and we will make sure
that this is all sorted out right away).

Re: [Ada] User Guide?

[dewar]

<<My question was: is this impractical on purely commercial grounds, ie
providing support to VMS people who do not want to hear about
UNIX, so the manual must either all VMS-ish or otherwise. Or is this
technically, texinfo-technology-wise impractical? If the latter, what
are the known technical problems?
>>

The point here is that unless we can meet the requirements of VMS users
in a single document, then we will be commited to having ACT maintain a
compeltely separate manual, which would force a compelte split here, and
we want to avoid that. There is no way that the gnu version of the manual
would stay up to date if that were to happen, and seeing as we think that
there are no insuperable technical problems, let's try that approach and
see if it works for everyone.

Re: [Ada] User Guide?

[dewar]

<<My question was: is this impractical on purely commercial grounds, ie
providing support to VMS people who do not want to hear about
UNIX, so the manual must either all VMS-ish or otherwise. Or is this
technically, texinfo-technology-wise impractical? If the latter, what
are the known technical problems?
>>

I really think we have a complete solution that will work just fine here,
so let's get that together, and then discuss whether it meets our needs.
Basically we are going to try to get a texi file that works just fine
for Unix as is, and then with some preprocessing, works fine for VMS.
I think this is quite doable, and meets all requirements.

Re: [Ada] User Guide?

[guerby]

Thanks for the update on documentation stuff! A detail though:

> This is impractical. For the VMS version, we must have complete removal of
> all unix stuff. This is really a requirement for the VMS version.

My question was: is this impractical on purely commercial grounds, ie
providing support to VMS people who do not want to hear about
UNIX, so the manual must either all VMS-ish or otherwise. Or is this
technically, texinfo-technology-wise impractical? If the latter, what
are the known technical problems?

-- 
Laurent Guerby <guerby@acm.org>

Re: [Ada] User Guide?

[dewar]

<<But we have ways of doing this, and we are working on the problem. Meanwhile
I have proposed that we just upload the Unix version for now, since it makes
no sense to have the compiler there without the documentation that is
essential for its use.
>>

We will either do this or get the final solution done ASAP.

Re: [Ada] User Guide?

[dewar]

Florian said:

>  To be honest, I have no idea which "open issues" Geert is talking
>  about.  There are still some things which have to be done, of course
>  (for example, some of the newer GNAT features added since 3.14 or so
>  are not documented, and markup is still inconsistent in a few places),
>  but this shouldn't stop us from committing the current ACT version to
>  CVS, followed by my changes which remove the need for preprocessing
>  (and which correct most of the markup issues).
>  
>  > With those fixed the file works.  What's the status of fixing those
>  > and the other Texinfo and other style issues I noted with
>  > gnat_rm.texi and gnat-style.texi?
>  
>  I've got patches for a few of them.  Some of them were already
>  submitted, IIRC one was applied, but the other ones were neither
>  approved nor rejected.
>  
>  I'm willing to do the remaining work, but only if I'm sure it won't be
>  ignored (and perhaps overtaken by changes to the internal ACT tree).

We will make sure that we coordinate with Florian on this, and try to get
this resolved as soon as possible. Florian, do not worry about being
ignored or overtaken here. This work is definitely useful, and we will
work with you to coordinate it.

Re: [Ada] User Guide?

[dewar]

<<The files checked into CVS should process in Texinfo without any special
magic or additional preprocessing, so they can go in onlinedocs.  It's OK
if this gives a Unix-style manual and the VMS one is given by using
-DVMSSTYLE to texi2dvi/makeinfo/....
>>

I think this should be achievable with the approach we have in mind for
the users guide. We will take care of the minor issues for gnat_rm.texi.

Re: [Ada] User Guide?

[dewar]

<<In the context of the GNU project, may be a unique all OS at once
manual makes more sense. I personnally don't mind having VMS style
switches next to the UNIX and GNU style ones all over the place.  Same
thing about having a little section per OS.  What do other people
think?
>>

This is impractical. For the VMS version, we must have complete removal of
all unix stuff. This is really a requirement for the VMS version.

But we have ways of doing this, and we are working on the problem. Meanwhile
I have proposed that we just upload the Unix version for now, since it makes
no sense to have the compiler there without the documentation that is
essential for its use.

Re: [Ada] User Guide?

[Florian Weimer]

"Joseph S. Myers" <jsm28@cam.ac.uk> writes:

> The files checked into CVS should process in Texinfo without any special
> magic or additional preprocessing, so they can go in onlinedocs.  It's OK
> if this gives a Unix-style manual and the VMS one is given by using
> -DVMSSTYLE to texi2dvi/makeinfo/....

I've produced version of the GNAT User Guide which doesn't require
special preprocessing.  It is based on the mid-November ACT version,
so I don't know if it's still up-to-date.  (It uses the suggested
-DVMS approach and some macros to work around Texinfo limitations.)

To be honest, I have no idea which "open issues" Geert is talking
about.  There are still some things which have to be done, of course
(for example, some of the newer GNAT features added since 3.14 or so
are not documented, and markup is still inconsistent in a few places),
but this shouldn't stop us from committing the current ACT version to
CVS, followed by my changes which remove the need for preprocessing
(and which correct most of the markup issues).

> With those fixed the file works.  What's the status of fixing those
> and the other Texinfo and other style issues I noted with
> gnat_rm.texi and gnat-style.texi?

I've got patches for a few of them.  Some of them were already
submitted, IIRC one was applied, but the other ones were neither
approved nor rejected.

I'm willing to do the remaining work, but only if I'm sure it won't be
ignored (and perhaps overtaken by changes to the internal ACT tree).

Re: [Ada] User Guide?

[Joseph S. Myers]

On Sat, 1 Dec 2001, Geert Bosch wrote:

> Yes, that is the reason. In particular, we have preprocessing done
> in order to get correct VMS documentation. This involves replacing
> mentions of UNIX-style options by VMS-style long ones and a number
> of other things. The preprocessor script is written in SPITBOL, which
> is not acceptable for the GCC tree.
> 
> We all agree this should be done using TeXinfo preprocessing magic if
> possible, or with a program in C or Ada otherwise (possibly using
> the GNAT.Spitbol package).

The files checked into CVS should process in Texinfo without any special
magic or additional preprocessing, so they can go in onlinedocs.  It's OK
if this gives a Unix-style manual and the VMS one is given by using
-DVMSSTYLE to texi2dvi/makeinfo/....

At present, gnat_rm.texi can't go in onlinedocs because it includes
nonexistent files texiplus (that include can be removed to make the file
work) and gfdl.texi (should be fdl.texi, in gcc/doc/include).  With those
fixed the file works.  What's the status of fixing those and the other
Texinfo and other style issues I noted with gnat_rm.texi and
gnat-style.texi?

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: [Ada] User Guide?

[guerby]

> Yes, that is the reason. In particular, we have preprocessing done
> in order to get correct VMS documentation. This involves replacing
> mentions of UNIX-style options by VMS-style long ones and a number
> of other things. The preprocessor script is written in SPITBOL, which
> is not acceptable for the GCC tree.
> 
> We all agree this should be done using TeXinfo preprocessing magic if
> possible, or with a program in C or Ada otherwise (possibly using
> the GNAT.Spitbol package).

Hmm, may be it made sense to have a fully VMS-ized manual in the
context of ACT distributing its software to VMS customers that are
100% against being reminded that anything remotely like UNIX can
possibly exist :) - you can replace VMS by any proprietary UNIX
against any other, the reasoning doesn't change. 

In the context of the GNU project, may be a unique all OS at once
manual makes more sense. I personnally don't mind having VMS style
switches next to the UNIX and GNU style ones all over the place.  Same
thing about having a little section per OS.  What do other people
think?

> Florian Weimer has already been working on this, but there were still
> some remaining issues. Please contact him for details.

Florian told me that the ball was in your court, may be an email got
lost? May be it's time to talk about it on this list?

-- 
Laurent Guerby <guerby@acm.org>

Re: [Ada] User Guide?

[Geert Bosch]

On Saturday, December 1, 2001, at 06:34 , <guerby@acm.org> wrote:

> I was just making a pass at the available Ada documentation and found
> only the GNAT Reference Manual in CVS (gnat_rm.texi). Is there any
> reason why the User Guide (gnat_ug.texi) is not in there yet? If
> it's just some stupid formatting to do, I volunteer, just drop me the
> file (IIRC I did the original SGI framemaker to texinfo pass, this will
> close the loop :).

Yes, that is the reason. In particular, we have preprocessing done
in order to get correct VMS documentation. This involves replacing
mentions of UNIX-style options by VMS-style long ones and a number
of other things. The preprocessor script is written in SPITBOL, which
is not acceptable for the GCC tree.

We all agree this should be done using TeXinfo preprocessing magic if
possible, or with a program in C or Ada otherwise (possibly using
the GNAT.Spitbol package).

Florian Weimer has already been working on this, but there were still
some remaining issues. Please contact him for details.

   -Geert

[Ada] User Guide?

[guerby]

I was just making a pass at the available Ada documentation and found
only the GNAT Reference Manual in CVS (gnat_rm.texi). Is there any
reason why the User Guide (gnat_ug.texi) is not in there yet? If
it's just some stupid formatting to do, I volunteer, just drop me the
file (IIRC I did the original SGI framemaker to texinfo pass, this will
close the loop :).

-- 
Laurent Guerby <guerby@acm.org>