Ada Reference Manual 2012 in info format

Ada Reference Manual 2012 in info format

[Stephen Leake]

I've posted the Ada Reference Manual 2012 in info format on my web page:

http://www.stephe-leake.org/ada/arm.html

This is draft 17 of ARM 2012, not yet formally approved by ISO. But
according to http://www.ada-auth.org/standards/ada12.html, there will
only be minor editorial changes, so this should be useful.

That file also includes the 2005 info files, with some bugs fixed in the
info format from my previous release. Useful for people stuck with
antiquated compilers :).

There's also a Debian package containing this waiting to be uploaded. If
you've ever felt the urge to get involved in Debian, now is the time! 
(I'm dropping out of Debian; I don't have time or energy anymore).

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Jerrid Kimball]

Thank you very much!  These are very nice and emacs seems to handle info 
pages very well.

I'm slowly getting to putting some modern-looking versions on the web 
based on the work of a fellow #ada IRC channel visitor.  I hope to get 
to it soon.  I'll keep CLA informed!

Cheers

On 04/29/2012 10:22 AM, Stephen Leake wrote:
> I've posted the Ada Reference Manual 2012 in info format on my web page:
>
> http://www.stephe-leake.org/ada/arm.html
>
> This is draft 17 of ARM 2012, not yet formally approved by ISO. But
> according to http://www.ada-auth.org/standards/ada12.html, there will
> only be minor editorial changes, so this should be useful.
>
> That file also includes the 2005 info files, with some bugs fixed in the
> info format from my previous release. Useful for people stuck with
> antiquated compilers :).
>
> There's also a Debian package containing this waiting to be uploaded. If
> you've ever felt the urge to get involved in Debian, now is the time!
> (I'm dropping out of Debian; I don't have time or energy anymore).
>

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Jerrid Kimball" <jerrid@kimball.co> wrote in message 
news:jnla59$h9e$1@munin.nbi.dk...
...
> I'm slowly getting to putting some modern-looking versions on the web 
> based on the work of a fellow #ada IRC channel visitor.  I hope to get to 
> it soon.  I'll keep CLA informed!

I suppose some people need to have a pile of eye-candy before they're 
willing to use anything. Sad.

For the record, the design of the Ada Standard HTML had two main criteria: 
(1) Look as similar to the PDF as possible; and (2) use only basic HTML 4 so 
that works on as many devices and browsers as possible. Those goals prevent 
the use of any significant eye-candy. (So does the desire to have these 
things work for people who insist on safe browsing - no scripts, no flash, 
no crap.)

The only changes I would make today is (1) more modern button designs (I 
lifted those from Windows NT 3.1, so they're a bit stale. :-) -- but 
unfortunately I'm neither an artist nor have much visual imagination, so I 
have no better ideas, and I haven't found anything better in the programs 
I've used (the LibreOffice icons make less sense than the ones in the 
Standard). And (2), I'd prefer to bound the maximum column width -- but 
that's not a possibility in CSS 1 or 2. (You can easily make a *fixed* 
column, but that would prevent using the Standard on small devices like my 
phone - a non-starter.)

The yellow background that you claimed to hate was done to differentiate the 
Standard from other pages that you're likely to have open in your browser: 
compiler documentation, ASIS, the Ada Rationales, etc. That came from other 
users that wanted to be able to see at a glance that they were looking at 
the Ada Standard and not some other page. I'd hate to lose that (not that we 
will in the "official" versions).

                                         Randy.

Re: Ada Reference Manual 2012 in info format

[Thomas Løcke]

On 05/01/2012 05:19 AM, Randy Brukardt wrote:
> I suppose some people need to have a pile of eye-candy before they're
> willing to use anything. Sad.



I don't think Jerrid is aiming for "a pile of eye-candy". If you take a
look at his http://planet.ada.cx/ website you'll see a very modern and
simple design. No eye-candy there, just a modern, easy to read and
straightforward carrier of information.

Modern does not equal "a pile of eye-candy".

 From what I know about Jerrid, I'm confident he'll whip up something
very nice for us to use.

-- 
Thomas L�cke | thomas@12boo.net | http://12boo.net

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Tue, 01 May 2012 08:06:21 +0200, Thomas Løcke <thomas@12boo.net> a  
écrit:

> On 05/01/2012 05:19 AM, Randy Brukardt wrote:
>> I suppose some people need to have a pile of eye-candy before they're
>> willing to use anything. Sad.
>
>
>
> I don't think Jerrid is aiming for "a pile of eye-candy". If you take a
> look at his http://planet.ada.cx/ website you'll see a very modern and
> simple design. No eye-candy there, just a modern, easy to read and
> straightforward carrier of information.
>
> Modern does not equal "a pile of eye-candy".

But that may equal “all sites looking the same”.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[J Kimball]

On 05/01/2012 01:06 AM, Thomas L�cke wrote:
> On 05/01/2012 05:19 AM, Randy Brukardt wrote:
>> I suppose some people need to have a pile of eye-candy before they're
>> willing to use anything. Sad.
>
>
>
> I don't think Jerrid is aiming for "a pile of eye-candy". If you take a
> look at his http://planet.ada.cx/ website you'll see a very modern and
> simple design. No eye-candy there, just a modern, easy to read and
> straightforward carrier of information.
>
> Modern does not equal "a pile of eye-candy".
>
>  From what I know about Jerrid, I'm confident he'll whip up something
> very nice for us to use.
>

You give me too much credit.  That's all Twitter's work, but it sure 
looks great and was cake to setup.  I've got a few styling ideas in mind 
that will sooner or later appear across that site.

Jerrid

[OT] CSS max-width (Was: Ada Reference Manual 2012 in info format)

[Jacob Sparre Andersen]

Randy Brukardt wrote:

> I'd prefer to bound the maximum column width -- but 
> that's not a possibility in CSS 1 or 2.

Isn't that what the "max-width" attribute does?

Greetings,

Jacob
-- 
�A corollary of Murphy's law is that duplicate information
 eventually becomes different information.  Putting both in
 the same file may slow down the process, but it will not
 prevent it.�                                 -- Wes Groleau

Re: [OT] CSS max-width (Was: Ada Reference Manual 2012 in info format)

[Yannick Duchêne (Hibou57)]

Le Thu, 03 May 2012 16:26:14 +0200, Jacob Sparre Andersen <sparre@nbi.dk>  
a écrit:

> Randy Brukardt wrote:
>
>> I'd prefer to bound the maximum column width -- but
>> that's not a possibility in CSS 1 or 2.
>
> Isn't that what the "max-width" attribute does?

Not supported by Internet Explorer, up to version 6 (later versions are  
OK), which is still widely in use in the industry and others corporations.  
Support in IE <=6, requires hacking.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: [OT] CSS max-width (Was: Ada Reference Manual 2012 in info format)

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1180 bytes --]

"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message 
news:op.wdqo2emfule2fv@douda-yannick...
Le Thu, 03 May 2012 16:26:14 +0200, Jacob Sparre Andersen <sparre@nbi.dk>
a �crit:

>> Randy Brukardt wrote:
>>
>>> I'd prefer to bound the maximum column width -- but
>>> that's not a possibility in CSS 1 or 2.
>>
>> Isn't that what the "max-width" attribute does?
>
>Not supported by Internet Explorer, up to version 6 (later versions are 
>OK), which is still widely in use in the industry and others corporations. 
>Support in IE <=6, requires hacking.

Thanks. I know it didn't work when I was laying out these pages; back then 
we had to support IE 5 and Netscape 7 and Firefox 1, all of which had 
problems with "fancy" CSS. We don't have to support the oldest of these 
anymore, but surely IE 6 still needs to be supported.

At some point soon, I ought to go back and retest all of the styles to see 
if any improvements can be made (the last major reworking of the styles was 
in early 2006). But I wouldn't change the layout that much; we don't want 
complex or fancy for this reference material.

                                            Randy.

Re: Ada Reference Manual 2012 in info format

[Jerrid Kimball]

On 04/30/2012 10:19 PM, Randy Brukardt wrote:
> "Jerrid Kimball"<jerrid@kimball.co>  wrote in message
> news:jnla59$h9e$1@munin.nbi.dk...
> ....
>> I'm slowly getting to putting some modern-looking versions on the web
>> based on the work of a fellow #ada IRC channel visitor.  I hope to get to
>> it soon.  I'll keep CLA informed!
>
> I suppose some people need to have a pile of eye-candy before they're
> willing to use anything. Sad.
>

It's really much more than that.  With a community of sites that 
generally look like Ada Home, no casual developer is going to stick 
around.  When the impression is that something is dead or near death who 
wants to invest any time, money or energy in it?  As a whole, we give 
this impression.  It's not necessarily our faults being left-brained and 
all, but at some point not presenting a modern face to the world at 
large hurts us as a whole.  AdaIC for example has done a decent job 
updating its appearance.

> For the record, the design of the Ada Standard HTML had two main criteria:
> (1) Look as similar to the PDF as possible; and (2) use only basic HTML 4 so
> that works on as many devices and browsers as possible. Those goals prevent
> the use of any significant eye-candy. (So does the desire to have these
> things work for people who insist on safe browsing - no scripts, no flash,
> no crap.)
 >
These are all noble goals, but I think they're silly in today's 
environment.  I think expecting a PDF to look like a webpage or vice 
versa (cue eye rolling).  Today's web looks a lot different than it did 
in 1995 and there's a point where you just have to say fuck it and leave 
those old devices in their own filth.  That's not to say that a modern, 
full-featured page can't be backward-compatible; we call is graceful 
degradation.  Of course, languages like Ruby or Python don't have great 
sites to operate across devices per se, but they look good and they're 
packed with info and the result is that they're bursting with 
popularity.  We're in a world where looks and features do matter. 
Blackberry is a better platform, but Apple has the apps.  Get it?  Being 
a bitchin' language isn't enough.  I'm more than pleased to use the 
official RM.  We have to get it together as a *brand* and quit being 
curmudgeonly engineers all the time and proselytize by not looking like 
a heap of fossils.

> The only changes I would make today is (1) more modern button designs (I
> lifted those from Windows NT 3.1, so they're a bit stale. :-) -- but
> unfortunately I'm neither an artist nor have much visual imagination, so I
> have no better ideas, and I haven't found anything better in the programs
> I've used (the LibreOffice icons make less sense than the ones in the
> Standard). And (2), I'd prefer to bound the maximum column width -- but
> that's not a possibility in CSS 1 or 2. (You can easily make a *fixed*
> column, but that would prevent using the Standard on small devices like my
> phone - a non-starter.
>
> The yellow background that you claimed to hate was done to differentiate the
> Standard from other pages that you're likely to have open in your browser:
> compiler documentation, ASIS, the Ada Rationales, etc. That came from other
> users that wanted to be able to see at a glance that they were looking at
> the Ada Standard and not some other page. I'd hate to lose that (not that we
> will in the "official" versions).
>
>                                           Randy.
>
>

Ideally I could spend all my time building the community and creating 
tools to make Ada more accessible, but alas I can not.

With love
Jerrid

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Jerrid Kimball" <jerrid@kimball.co> wrote in message 
news:jnu7u0$16o$1@munin.nbi.dk...
> On 04/30/2012 10:19 PM, Randy Brukardt wrote:
...
>> I suppose some people need to have a pile of eye-candy before they're
>> willing to use anything. Sad.
>
> It's really much more than that.  With a community of sites that generally 
> look like Ada Home, no casual developer is going to stick around.  When 
> the impression is that something is dead or near death who wants to invest 
> any time, money or energy in it?

AdaHome, of course, is dead and has been for 15 years. If people look at 
dead sites first, surely they *are* going to have a problem that way. (I'm 
not sure why it even stays on the 'net).

>  As a whole, we give this impression.  It's not necessarily our faults 
> being left-brained and all, but at some point not presenting a modern face 
> to the world at large hurts us as a whole.  AdaIC for example has done a 
> decent job updating its appearance.

You're probably right; the superficial is far more important these days than 
any substance (of which there is precious little). In all seriousness, this 
is not a world that I care to inhabit. Ada has tended to be the rare 
exception to that.

>> For the record, the design of the Ada Standard HTML had two main 
>> criteria:
>> (1) Look as similar to the PDF as possible; and (2) use only basic HTML 4 
>> so
>> that works on as many devices and browsers as possible. Those goals 
>> prevent
>> the use of any significant eye-candy. (So does the desire to have these
>> things work for people who insist on safe browsing - no scripts, no 
>> flash,
>> no crap.)
> >
> These are all noble goals, but I think they're silly in today's 
> environment.  I think expecting a PDF to look like a webpage or vice versa 
> (cue eye rolling).

The PDF (and the printed page) for the Ada Reference Manual is very readable 
and a great way to impart the information. The navigation is admittedly, 
terrible. The reason that I lobbied for the HTML version in the first place 
was to get that extra navigation (the HTML links the index, the syntax, and 
the cross-references). But there is no reason whatsoever to lose the 
readability of the original just to get extra navigation.

I can see efforts to further improve the navigation and presentation in 
narrow ways (in particular, preventing really long lines on wide screens). 
But the entire point of the ARM is to present information concisely -- too 
much eye candy is going to detract a lot from that (just as it does on the 
new AdaIC website).

>  Today's web looks a lot different than it did in 1995 and there's a point 
> where you just have to say fuck it and leave those old devices in their 
> own filth.

Yeah, most sites are hardly useable unless you allow them to show you 
malware-laden ads and run god-knows-what on your computer. It's all change 
for the sake of change; there's no benefit to most of it, and it wastes 
everyone's time -- they could have been building something useful to 
humanity, but instead they're fiddling with colors and fonts. (And those big 
corporations want it that way -- much less likely that you'll come up with 
something truely disruptive that they can't copy.)

>We have to get it together as a *brand* and quit being curmudgeonly 
>engineers all the time and proselytize by not looking like a heap of 
>fossils.

We're not going to get together around that. I *am* a fossil and proud of 
it. I much prefer using things that work rather than changing them just for 
the sake of change. Yes, I much prefer the look of Windows 2000 to any of 
the later versions -- in large part because the changes brought almost no 
improvement in usability. (For that, a disruptive change, like moving to the 
touch interfaces of modern phones, is needed. Incremental improvements are 
OK only if they are completely compatible, something almost every software 
developer seems to forget.)

That isn't to say that change is necessarily bad, but it has to have *clear* 
benefits for the time (relearning in particular) and money investment. The 
vast majority doesn't have that, and a lot of a obvious step backwards 
(where important functionality disappears - much like Microsoft deciding 
that we don't need a Start Menu in Windows 8 -- I almost exclusively use the 
Start Menu to launch GUI programs, I never, ever use the desktop to launch 
programs, occassionally by double-clicking on a file (but that's rather 
rare).

Enough ranting.

If you do spend time making an alternative version of the Standard, I 
strongly recommend that you do so by modifying the ARM_Formatter tool. That 
way, you can convert future versions of the Standard to your format easily 
(if it is a by-hand conversion, it will become obsolete far quicker than you 
realize and then you'll either have to do it all again or forget it). And 
that would also allow the alternate version to be used on the Rationale and 
other standards documents, if that is appropriate someday. (That's what 
Stephen Leake did with the "info" version.)

                                              Randy.

Re: Ada Reference Manual 2012 in info format

[BrianG]

On 05/03/2012 07:25 PM, Randy Brukardt wrote:
> "Jerrid Kimball"<jerrid@kimball.co>  wrote in message
> news:jnu7u0$16o$1@munin.nbi.dk...
>> On 04/30/2012 10:19 PM, Randy Brukardt wrote:
> ...
>>   Today's web looks a lot different than it did in 1995 and there's a point
>> where you just have to say fuck it and leave those old devices in their
>> own filth.
>
> Yeah, most sites are hardly useable unless you allow them to show you
> malware-laden ads and run god-knows-what on your computer. It's all change
> for the sake of change; there's no benefit to most of it, and it wastes
> everyone's time -- they could have been building something useful to
> humanity, but instead they're fiddling with colors and fonts.

Many times this doesn't waste just people's time.  It also wastes CPU 
time.  I'm writing this on a a 10", single core, 900MHz netbook.  On 
many 'modern' web pages, it runs at 100% CPU speed, 90-100% CPU load - 
after the page has been fully loaded (this is usually from ads added to 
pay for the 'free' site, but comes from developers not paying attention 
to these issues - and is often unnecessary).  Otherwise (e.g. on 
'lesser' web pages), it runs at 12.5% CPU speed, <10% CPU load.  That's 
a big impact on battery life, other tasks running, and possibly 
heat/cooling.

Yeah, my computer is old, but its specs are very similar to many of 
those 'non-traditional' web browsing devices being used now (smart 
phones, tablets, etc.).  Even as those devices start upping their CPUs 
and cores, there'll be new 'lower-end' device types coming along.

-- 
---
BrianG
000
@[Google's email domain]
.com

Re: Ada Reference Manual 2012 in info format

[Oliver Kleinke]

Am Thu, 3 May 2012 18:25:53 -0500
schrieb "Randy Brukardt" <randy@rrsoftware.com>:

> If you do spend time making an alternative version of the Standard, I 
> strongly recommend that you do so by modifying the ARM_Formatter
> tool. That way, you can convert future versions of the Standard to
> your format easily (if it is a by-hand conversion, it will become
> obsolete far quicker than you realize and then you'll either have to
> do it all again or forget it). And that would also allow the
> alternate version to be used on the Rationale and other standards
> documents, if that is appropriate someday. (That's what Stephen Leake
> did with the "info" version.)
> 
>                                               Randy.

Hello Randy,

you have to realize that design and looks do have a function beyond
fancy, usability for example. I think you derailed the conversation for
your own purpose of defending the RM from change. "malware-laden ads",
"run god-knows-what on your computer", "Start Menu in Windows 8" --
these are cheesy strawman arguments and it sounds like you are accusing
Jerrid that this is what he has in mind.

I am writing an XML extension to the formatter. It's not finished yet
but does already look promising. Why XML? Because it's easily
transformable into nearly every other format (Original Source format,
plain-text, HTML, PDF, DocBook, DITA, info, SQL inserts, you name it..)
using XSL (I'm talking XSLT + XSL-FO). A major problem of the
formatter/RM sources is that they only provide partial semantic
information about the contents, that IS 1995-style. Honestly, you should
consider converting the sources to a more appropriate format. Also, the
way the Formatter sources are provided sucks major -- cvsweb, you have
to click around a lot until you have a complete set of files plus some
of the HEAD versions have been broken.

Providing a modern HTML version does not exclude the possibility to
provide a more 'compatible' version, so don't be so obstinate. :-)

Cheers,
Oliver

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 5/9/2012 6:17 AM, Oliver Kleinke wrote:

>
> I am writing an XML extension to the formatter. It's not finished yet
> but does already look promising. Why XML? Because it's easily
> transformable into nearly every other format (Original Source format,
> plain-text, HTML, PDF, DocBook, DITA, info, SQL inserts, you name it..)
> using XSL (I'm talking XSLT + XSL-FO). A major problem of the
> formatter/RM sources is that they only provide partial semantic
> information about the contents, that IS 1995-style. Honestly, you should
> consider converting the sources to a more appropriate format. Also, the
> way the Formatter sources are provided sucks major -- cvsweb, you have
> to click around a lot until you have a complete set of files plus some
> of the HEAD versions have been broken.
>
> Providing a modern HTML version does not exclude the possibility to
> provide a more 'compatible' version, so don't be so obstinate. :-)
>
> Cheers,
> Oliver

hi,

I do not know much about XML (other than using it to make
some Ant script to build some Java program I have).

I use Latex for all my documents, and use Latex2html to convert
to HTML and pdflatex to convert to PDF. It works pretty well.

If there are some math in the document, I think Latex is the best
choice to use. I think XML is not good for math.

Now, on a different angle, I've just read Oracle made its
latest Java language reference (Java SE7) using DocBook.

http://docs.oracle.com/javase/specs/jls/se7/html/jls-0-preface7.html

"This edition is the first to be written in the DocBook
format. Metadata in the XML markup forms a kind of static
type system"

Which seems to support what you are saying about XML. It seems
DocBook is XML based also.

I'd use XML, except that my documents and reports (for
school) are full of math, and Latex is the best for
that.

I like Latex, and I find it very easy to use.

Any way, just thought to mention this on the side.

--Nasser

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:

> I think XML is not good for math.

XML is not good for anything.  I don't care about Web but in automation it
becomes a growing problem that precious bandwidth and human resources are
spent on chewing XML mess.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Georg Bauhaus]

On 09.05.12 15:00, Dmitry A. Kazakov wrote:
> On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:
> 
>> I think XML is not good for math.
> 
> XML is not good for anything.  I don't care about Web but in automation it
> becomes a growing problem that precious bandwidth and human resources are
> spent on chewing XML mess.

Writing math papers and making data traveling automation networks
seem rather different use cases.

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Wed, 09 May 2012 15:56:32 +0200, Georg Bauhaus wrote:

> On 09.05.12 15:00, Dmitry A. Kazakov wrote:
>> On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:
>> 
>>> I think XML is not good for math.
>> 
>> XML is not good for anything.  I don't care about Web but in automation it
>> becomes a growing problem that precious bandwidth and human resources are
>> spent on chewing XML mess.
> 
> Writing math papers and making data traveling automation networks
> seem rather different use cases.

Yes, though XML is usually advocated as a universal solution for
everything.

Just two weeks ago, or so, XML was proposed to handle Ada source code.

Wouldn't be great to have math in XML:

<operation name='*'>
   <number>
     <digit position=1>3</digit>
     <digit position=2>1</digit>
   </number>
   <number>
     <digit position=1>5</digit>
     <digit position=2>6</digit>
   </number>
...

no?

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Ludovic Brenta]

Dmitry A. Kazakov wrote on comp.lang.ada:
> Wouldn't be great to have math in XML:
> 
> <operation name='*'>
>    <number>

Make that <number base="10" digit_order="high-order-first">

>      <digit position=1>3</digit>
>      <digit position=2>1</digit>
>    </number>
>    <number>

and <number base=7 digit_order="low-order-first">

>      <digit position=1>5</digit>
>      <digit position=2>6</digit>
>    </number>
> ...
> 
> no?

yes! :)

-- 
Ludovic Brenta.
A reliable implication interacts with win-win solutions.

Re: Ada Reference Manual 2012 in info format

[Georg Bauhaus]

On 09.05.12 16:09, Dmitry A. Kazakov wrote:

>> Writing math papers and making data traveling automation networks
>> seem rather different use cases.
> 
> Yes, though XML is usually advocated as a universal solution for
> everything.

Suggestions to use XML can be motivated by the force of what everyone
else does. So the best options seems to be to clearly demonstrate
responsibility of followers for any cost incurred by inappropriate
use of XML.


> Just two weeks ago, or so, XML was proposed to handle Ada source code.

One way to "generalize" an algorithm so that it can be used with
any capable language, or presented to "analytical" programs, is to describe
it superficially, and loose something.

The XML format would not be made for programming, obviously, since then we
could stop using specialized programming languages. But, as was said
in this thread, XML of the kind that is sufficiently general is easily
transformed from and into some other formalism.
A more generic source code analysis tool may then analyze just the
basic idea, if and only if that is covered in simplified XML.

Much like a mathematical description of an algorithm can be transformed
into a program, and more easily so if the math is sufficiently general,
and sufficiently conventional. With generality you loose something, but
the loss seems preferable to inscrutable duct tape software written using
every feature of a programming language.

procedure Foo
   ( Bar : in out T1;
     Baz : in     F17);
  --  does this thing

becomes, or is made from, not for reading(!),

<subp n="Foo">
  <a:doc>does this thing</a:doc>
  <sig>
    <par n="Bar" type="T1" mode="inout" />
    <par n="Baz" type="F17" mode="in" />
  <sig>
</subp>


Programs that use XML processors and XSL for performing I/O
would then not have to know about Ada, C++, C#, Java, Cobol,
VB, etc.

> Wouldn't be great to have math in XML:

The XML text is not well-formed, you need more Ada like verbosity :-)

>      <digit position=1>3</digit>
>      <digit position=2>1</digit>

<digit position="1">3</digit>
<digit position="2">1</digit>

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Wed, 09 May 2012 18:33:49 +0200, Georg Bauhaus wrote:

> On 09.05.12 16:09, Dmitry A. Kazakov wrote:
> 
>>> Writing math papers and making data traveling automation networks
>>> seem rather different use cases.
>> 
>> Yes, though XML is usually advocated as a universal solution for
>> everything.
> 
> Suggestions to use XML can be motivated by the force of what everyone
> else does. So the best options seems to be to clearly demonstrate
> responsibility of followers for any cost incurred by inappropriate
> use of XML.

"Nobody ever got fired for buying IBM"

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Jerrid Kimball]

On 05/09/2012 09:09 AM, Dmitry A. Kazakov wrote:
> On Wed, 09 May 2012 15:56:32 +0200, Georg Bauhaus wrote:
>
>> On 09.05.12 15:00, Dmitry A. Kazakov wrote:
>>> On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:
>>>
>>>> I think XML is not good for math.
>>>
>>> XML is not good for anything.  I don't care about Web but in automation it
>>> becomes a growing problem that precious bandwidth and human resources are
>>> spent on chewing XML mess.
>>
>> Writing math papers and making data traveling automation networks
>> seem rather different use cases.
>
> Yes, though XML is usually advocated as a universal solution for
> everything.
>
> Just two weeks ago, or so, XML was proposed to handle Ada source code.
>
> Wouldn't be great to have math in XML:
>
> <operation name='*'>
>     <number>
>       <digit position=1>3</digit>
>       <digit position=2>1</digit>
>     </number>
>     <number>
>       <digit position=1>5</digit>
>       <digit position=2>6</digit>
>     </number>
> ....
>
> no?
>

Oliver was hardly suggesting that XML is universal solution, good grief. 
  However, XML is a huge player on many fronts for a number of reasons 
including being easily readable by humans and being standardized.  There 
are, of course, instances where XML has been abused in very horrible 
ways--what hasn't been (Yes, even Ada has been.  You know it!)--but this 
in no way precludes it from being used for its intended purpose as a 
language for describing documents.  What an idea!  Obviously this will 
never change, but I'm sure we'll have good fun with the XML.

Keep in mind you are no obliged to come anywhere near it if you do not 
so desire.  So--and this is directed at Randy also--feel free to stay 
away from anything Oliver or I perceive as innovations on the front of 
community building ad if you don't have useful discourse, let your keys 
be silent because this sort of banter isn't helping him, me, CLA, Ada or 
anyone or anything else.  It's just trolling.  The limited bandwidth of 
your automation system networks and other difficulties you encounter are 
hardly relevant to RM formatting and frankly aren't even worth 
mentioning in this discussion.  George said it well with brevity. :)

That example is a bit far-fetched, too--almost obnoxiously so.  That's 
the sort of XML you might see on a late night infomercial for YAML. 
"Does your XML look this?"  "Don't you hate all those *ugly* tags?" 
"Always cutting yourself on those pesky brackets?"

I'm not entirely sure of the endianness of your numbers (you specified 
everything except the most obvious), but I imagine it could be reduced 
to a single tag.  It would depend on a lot of factors, but something 
like this doesn't seem out of the question:

<multiply>
    <left>31</left>
    <right>56</right>
</multiple>

or dare I suggest:

<multiply operands="31 56" /> <!-- multiplication is commutative after 
all -->

or have I gone too far?

Of course DSA has to represent things across the line.  I haven't done a 
whole lot with it, so far.  How does GIOP send data across the line?

That's my contribution for the day.

Have a good one.

Oliver ;)


-
Jerrid

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Wed, 09 May 2012 11:51:22 -0500, Jerrid Kimball wrote:

>   However, XML is a huge player on many fronts for a number of reasons 
> including being easily readable by humans and being standardized.

Ah, I see, but then I really fail to understand the problem with RM. If XML
and HTML are human readable what is the buzz about its design? Anybody can
open the document's source in the notepad, even in Emacs (sic!), and enjoy
highly readable angular brackets in their lucid clarity unhindered by
intervention of nasty page renderers... (:-))

> There 
> are, of course, instances where XML has been abused in very horrible 
> ways--what hasn't been (Yes, even Ada has been.  You know it!)--but this 
> in no way precludes it from being used for its intended purpose as a 
> language for describing documents.

Describing? Not designing, also? 

> I'm not entirely sure of the endianness of your numbers (you specified 
> everything except the most obvious), but I imagine it could be reduced 
> to a single tag.  It would depend on a lot of factors, but something 
> like this doesn't seem out of the question:
> 
> <multiply>
>     <left>31</left>
>     <right>56</right>
> </multiple>
> 
> or dare I suggest:
> 
> <multiply operands="31 56" /> <!-- multiplication is commutative after 
> all -->
> 
> or have I gone too far?

I am afraid yes. You are just one step away from <f>"32*56"</f>, and two
from (God save us for such an unreadable gibberish): 32*56! (:-))
 
> Of course DSA has to represent things across the line.  I haven't done a 
> whole lot with it, so far.  How does GIOP send data across the line?

We are using our own binary protocol to exchange data.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Georg Bauhaus]

On 09.05.12 19:21, Dmitry A. Kazakov wrote:
> On Wed, 09 May 2012 11:51:22 -0500, Jerrid Kimball wrote:

>> or dare I suggest:
>>
>> <multiply operands="31 56" />  <!-- multiplication is commutative after
>> all -->
>>
>> or have I gone too far?
>
> I am afraid yes. You are just one step away from<f>"32*56"</f>, and two
> from (God save us for such an unreadable gibberish): 32*56! (:-))

I would guess that the latter expression means, to many,
32 to the power of 56 factorial.

The first literal looks much more like a regular language, because
of the quotes: prefix "3" followed by an arbitrary number of "2"s, suffix "56".

The point is that a few words will resolve all ambiguity *immediately*.
Most desirable when documents like LRM ISO/IEC 8652 talk about Ada,
C, Cobol, and Fortran at the same time.

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Georg Bauhaus <rm.dash-bauhaus@futureapps.de> writes:

> On 09.05.12 19:21, Dmitry A. Kazakov wrote:
>> On Wed, 09 May 2012 11:51:22 -0500, Jerrid Kimball wrote:
>
>>> or dare I suggest:
>>>
>>> <multiply operands="31 56" />  <!-- multiplication is commutative after
>>> all -->
>>>
>>> or have I gone too far?
>>
>> I am afraid yes. You are just one step away from<f>"32*56"</f>, and two
>> from (God save us for such an unreadable gibberish): 32*56! (:-))
>
> I would guess that the latter expression means, to many,
> 32 to the power of 56 factorial.
>
> The first literal looks much more like a regular language, because
> of the quotes: prefix "3" followed by an arbitrary number of "2"s, suffix "56".

Excellent examples of ambiguity!

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Simon Wright]

Jerrid is right.

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Jerrid Kimball" <jerrid@kimball.co> wrote in message 
news:joe7ad$ntc$1@munin.nbi.dk...
...
> So--and this is directed at Randy also--feel free to stay away from 
> anything Oliver or I perceive as innovations on the front of community 
> building ad if you don't have useful discourse, ...

As I said to Oliver, I don't want to see a fork in the (HTML) Standard, even 
in its presentation. What I *would* like to see is some concrete suggestions 
for improving the navigation and readability of the existing HTML Standard. 
That would lift *all* boats. After all, I can regenerate and repost *all* of 
the versions of the Ada Standard going back to Ada 95 with improvements 
(I've done that several times as bugs and problems with newer browsers have 
been uncovered). And I admit, I have no idea of what you think a "modern" 
website ought to look like. All of the ones I look at waste large amounts of 
screen space on ads, which certainly is "modern" but is a trend that 
hopefully has nothing to do with the Ada Standard (or any other public 
documents, for that matter).

I really don't like when people intend to "improve" something without making 
suggestions to the original author, who probably has a much better idea of 
the intended usages and the gotchas than anyone else could.

Anyway, enough griping. I'm interested in concrete suggestions that can be 
implemented (not to promise that they would be). But be aware that I don't 
have much budget for RM work at this point, so I can't promise anything.

                          Randy.

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Wed, 9 May 2012 20:42:56 -0500, Randy Brukardt wrote:

> Anyway, enough griping. I'm interested in concrete suggestions that can be 
> implemented (not to promise that they would be). But be aware that I don't 
> have much budget for RM work at this point, so I can't promise anything.

I would lump everything in just one HTML page. Index and contents could be
in a separate frame, but not really necessary.


-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 5/10/2012 2:21 AM, Dmitry A. Kazakov wrote:
> On Wed, 9 May 2012 20:42:56 -0500, Randy Brukardt wrote:
>
>> Anyway, enough griping. I'm interested in concrete suggestions that can be
>> implemented (not to promise that they would be). But be aware that I don't
>> have much budget for RM work at this point, so I can't promise anything.
>

> I would lump everything in just one HTML page. Index and contents could be
> in a separate frame, but not really necessary.
>

Why not use Latex? Then you get the full 30 years of latex
scientific publication tools that Latex has, with all the
indexing, table of contents, bibliography, page numbers,
cross referneces, tables, figure, graphics, etc.. and
zillions of latex packages that comes with it for free.

Then use Latex2html to convert everything to HTML. Use
pdflatex to generate PDF, generate .ps etc... all from
the SAME plain text source files.  see

http://www.tug.org/texlive/
http://www.maths.ox.ac.uk/help/faqs/latex/conversions

I do not know why any one will choose a different tool
to publish anything. It is all there ;)

--Nasser

Re: Ada Reference Manual 2012 in info format

[Simon Wright]

"Nasser M. Abbasi" <nma@12000.org> writes:

> Why not use Latex? Then you get the full 30 years of latex
> scientific publication tools that Latex has, with all the
> indexing, table of contents, bibliography, page numbers,
> cross referneces, tables, figure, graphics, etc.. and
> zillions of latex packages that comes with it for free.
>
> Then use Latex2html to convert everything to HTML. Use
> pdflatex to generate PDF, generate .ps etc... all from
> the SAME plain text source files.  see
>
> http://www.tug.org/texlive/
> http://www.maths.ox.ac.uk/help/faqs/latex/conversions
>
> I do not know why any one will choose a different tool
> to publish anything. It is all there ;)

For me, at any rate, latex2html produces incomplete and nasty-looking
output. I agree about pdflatex, though (especially with hyperref).

Re: Ada Reference Manual 2012 in info format

[Jacob Sparre Andersen]

Nasser M. Abbasi wrote:

> Why not use Latex? [...]

> Then use Latex2html to convert everything to HTML.

There is already an HTML formatter for the RM.  (And the output from
"latex2html" is not the most beautiful web pages I've seen.)

Greetings,

Jacob
-- 
"I'm going as a barrel of toxic waste!"

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 5/10/2012 5:44 AM, Jacob Sparre Andersen wrote:
> Nasser M. Abbasi wrote:
>
>> Why not use Latex? [...]
>
>> Then use Latex2html to convert everything to HTML.
>
> There is already an HTML formatter for the RM.  (And the output from
> "latex2html" is not the most beautiful web pages I've seen.)
>
> Greetings,
>
> Jacob

Well, Latex2html might not be perfect, I agree, but
for someone using Latex, it is the best there is to
convert from Latex to HTML.  I tried many other tools.

Here is an example

---------------------------------------
Javier Miranda's Ada Corner
Free Book: A Detailed Description of the GNU Ada Run-Time (J.Miranda, 2002)

http://www.iuma.ulpgc.es/~jmiranda/
-----------------------------------------

The link to his book is right there near the top.

The book was written in Latex, converted to HTML, PDF,
PS, DVI.

I think it looks _really_ nice.

Any way, I thought just to suggest Latex. I know it is
mainly used by those who use Math more than
anything else, but I myself use it to write everything now
not just for my school HW's which has math.

--Nasser

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

"Nasser M. Abbasi" <nma@12000.org> writes:

> Well, Latex2html might not be perfect, I agree, but
> for someone using Latex, it is the best there is to
> convert from Latex to HTML.  I tried many other tools.
>
> Here is an example
>
> ---------------------------------------
> Javier Miranda's Ada Corner
> Free Book: A Detailed Description of the GNU Ada Run-Time (J.Miranda, 2002)
>
> http://www.iuma.ulpgc.es/~jmiranda/
> -----------------------------------------
>
> The link to his book is right there near the top.

The table of contents has no numbers! How do I find section 4.5.2?


-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 5/11/2012 6:49 AM, Stephen Leake wrote:
> "Nasser M. Abbasi"<nma@12000.org>  writes:

>> Here is an example
>>
>> ---------------------------------------
>> Javier Miranda's Ada Corner
>> Free Book: A Detailed Description of the GNU Ada Run-Time (J.Miranda, 2002)
>>
>> http://www.iuma.ulpgc.es/~jmiranda/
>> -----------------------------------------
>>
>> The link to his book is right there near the top.
>

> The table of contents has no numbers! How do I find section 4.5.2?
>

This is just an option. The author of the above decided not to generate
table of content with numbers, but this is just a Latex2html
option. Dr Miranda above has his Makefiles used to build the book,
so any one can change this options.

I use sections numbers myself. Here is an example of mine
generated by Latex2html. It it the same table of content that
generated by Latex. Just converted to HTML with links.

http://12000.org/my_notes/stress_measures/KERNEL/index.htm

Sorry, I never heard of 'Scheme' that you mentioned. But
this does not mean anything really. There are so many
things I never heard about.

good luck with the RM work everyone! I think Ada RM
looks the best of any other language RM document I've seen.

Lots of hardwork must have gone into making it.

--Nasser
  

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 10/05/2012 9:35, Nasser M. Abbasi escribi�:
>...
> Why not use Latex? Then you get the full 30 years of latex
> scientific publication tools that Latex has, with all the
> indexing, table of contents, bibliography, page numbers,
> cross referneces, tables, figure, graphics, etc.. and
> zillions of latex packages that comes with it for free.
>
> Then use Latex2html to convert everything to HTML. Use
> pdflatex to generate PDF, generate .ps etc... all from
> the SAME plain text source files. see
>
> http://www.tug.org/texlive/
> http://www.maths.ox.ac.uk/help/faqs/latex/conversions
>
> I do not know why any one will choose a different tool
> to publish anything. It is all there ;)

LaTeX is excellent in creating the final publishing format. But it lacks 
enough separation between contents and presentation. Other XML-based 
markup languages, like DocBook or DITA, seem much more appropriate as 
contents source code. They contain little presentation style 
information, or none at all. Converting them to the final publishing 
format is the role of a separate, companion stylesheet or utility.

This way the same source can be effectively converted to a bunch of 
final formats with moderate effort.

IMHO, the most promising line of attack is to keep the current source 
markup, and provide a lossless XML export facility.

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 17:05:33 +0200, Manuel Collado  
<m.collado@domain.invalid> a écrit:

> LaTeX is excellent in creating the final publishing format. But it lacks  
> enough separation between contents and presentation. Other XML-based  
> markup languages, like DocBook or DITA, seem much more appropriate

Even more DITA, and the authoring style which comes with it (and which is  
already there anyway in the actual RM authoring style). To my opinion, if  
DocBook is to be favored for something, that would be for learning  
materials, where a document is to be read from start to end, as an  
uninterrupted flow. The RM is more like a random‑access access document,  
with many self‑sufficient parts.

> IMHO, the most promising line of attack is to keep the current source  
> markup, and provide a lossless XML export facility.

I vote for that one too. Would be too much a nightmare with too few added  
value for Randy, to switch to another source format. If there is something  
to do at the source level, that's just to avoid potential lack of semantic  
markup (I noticed some a long time ago, but forget where, sorry, will tell  
if I land to it again).


-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 10/05/2012 17:42, Yannick Duchêne (Hibou57) escribió:
> Le Thu, 10 May 2012 17:05:33 +0200, Manuel Collado
> <m.collado@domain.invalid> a écrit:
>
>> LaTeX is excellent in creating the final publishing format. But it
>> lacks enough separation between contents and presentation. Other
>> XML-based markup languages, like DocBook or DITA, seem much more
>> appropriate
>
> Even more DITA, and the authoring style which comes with it (and which
> is already there anyway in the actual RM authoring style). To my
> opinion, if DocBook is to be favored for something, that would be for
> learning materials, where a document is to be read from start to end, as
> an uninterrupted flow. The RM is more like a random‑access access
> document, with many self‑sufficient parts.
>
>> IMHO, the most promising line of attack is to keep the current source
>> markup, and provide a lossless XML export facility.
>
> I vote for that one too. Would be too much a nightmare with too few
> added value for Randy, to switch to another source format. If there is
> something to do at the source level, that's just to avoid potential lack
> of semantic markup (I noticed some a long time ago, but forget where,
> sorry, will tell if I land to it again).

Please note that I'm not suggesting a direct conversion/export from the 
current markup to DITA. My preference is to just translate each current 
mark to an equivalent XML tag. This way the full structure and contents 
of the ARM is preserved, while allowing immediate application of 
standard XML tools and techniques to process it for producing additional 
final formats (single-page HTML, MS-Windows HTML help, Latex->PDF with 
working links, FOP->PDF with working links, DocBook, DITA, and more).

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 00:15:19 +0200, Manuel Collado  
<m.collado@domain.invalid> a écrit:
> Please note that I'm not suggesting a direct conversion/export from the  
> current markup to DITA. My preference is to just translate each current  
> mark to an equivalent XML tag. This way the full structure and contents  
> of the ARM is preserved, while allowing immediate application of  
> standard XML tools […]

You're fine, that's what I did understand. Feel free to tell me when this  
done (e‑mail is OK), I will then start to design an XSLT transform for  
this output. If you need help, tell me too.

Hint: don't forget about the xml:space="preserve" attribute for Ada source  
snippet elements ;). I believe this should include syntax rules as well,  
as these are often subject to source formating too.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 11/05/2012 3:16, Yannick Duchêne (Hibou57) escribió:
> Le Fri, 11 May 2012 00:15:19 +0200, Manuel Collado
> <m.collado@domain.invalid> a écrit:
>> Please note that I'm not suggesting a direct conversion/export from
>> the current markup to DITA. My preference is to just translate each
>> current mark to an equivalent XML tag. This way the full structure and
>> contents of the ARM is preserved, while allowing immediate application
>> of standard XML tools […]
>
> You're fine, that's what I did understand. Feel free to tell me when
> this done (e‑mail is OK), I will then start to design an XSLT transform
> for this output. If you need help, tell me too.

My intention wasn't to develop the XML export facility myself, but to 
develop post-processors, like you offer. It seems that the ARM 
maintainers are considering to offer the XML export format sometime in 
the future.

Anyway I could eventually develop my own converter for the Scribe 
notation. Is there a publicly accessible place that documents it?

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 12:47:44 +0200, Manuel Collado  
<m.collado@domain.invalid> a écrit:

> El 11/05/2012 3:16, Yannick Duchêne (Hibou57) escribió:
>> Le Fri, 11 May 2012 00:15:19 +0200, Manuel Collado
>> <m.collado@domain.invalid> a écrit:
>>> Please note that I'm not suggesting a direct conversion/export from
>>> the current markup to DITA. My preference is to just translate each
>>> current mark to an equivalent XML tag. This way the full structure and
>>> contents of the ARM is preserved, while allowing immediate application
>>> of standard XML tools […]
>>
>> You're fine, that's what I did understand. Feel free to tell me when
>> this done (e‑mail is OK), I will then start to design an XSLT transform
>> for this output. If you need help, tell me too.
>
> My intention wasn't to develop the XML export facility myself
So I've indeed missed something. Ok.

> Anyway I could eventually develop my own converter for the Scribe  
> notation. Is there a publicly accessible place that documents it?
As I said, I had a similar intent. Your idea of a more general output is  
good. If I start it in the future (*), I will go for your idea, better  
than my initial one.

Have a nice day Manuel

(*) Won't be before some time.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Manuel Collado" <m.collado@domain.invalid> wrote in message 
news:joiqoe$ca9$1@speranza.aioe.org...
...
> Anyway I could eventually develop my own converter for the Scribe 
> notation. Is there a publicly accessible place that documents it?

There is a document "Command.Txt" that is supposed to document everything 
about the format used by Arm_Form. I refer to it all the time (I originally 
did this 12 years ago, so I forgotten plenty about it). You can find it in 
the version control with the rest of Arm_Form source code.

                              Randy.

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 12/05/2012 2:52, Randy Brukardt escribi�:
> "Manuel Collado"<m.collado@domain.invalid>  wrote in message
> news:joiqoe$ca9$1@speranza.aioe.org...
> ...
>> Anyway I could eventually develop my own converter for the Scribe
>> notation. Is there a publicly accessible place that documents it?
>
> There is a document "Command.Txt" that is supposed to document everything
> about the format used by Arm_Form. I refer to it all the time (I originally
> did this 12 years ago, so I forgotten plenty about it). You can find it in
> the version control with the rest of Arm_Form source code.
>
>                                Randy.

Thanks for the pointer. In fact I've just discovered it myself. But is 
it good having a confirmation.

I've discovered also a very old documentation about the Scribe original 
markup:

http://bitsavers.informatik.uni-stuttgart.de/pdf/cmu/scribe/Scribe_Introductory_Users_Manual_Jul78.pdf

A scan of an old printout, apparently made with a fixed-pith drum impact 
printer of the time.

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Manuel Collado <m.collado@domain.invalid> writes:

> My intention wasn't to develop the XML export facility myself, but to
> develop post-processors, like you offer. It seems that the ARM
> maintainers are considering to offer the XML export format sometime in
> the future.

You have misunderstood. Neither Randy (primary author of the ARM and
arm_form Ada code), nor me (author of texinfo portion of arm_form Ada
code) have said we will _do_ the XML export. We have said it would be
good to have.

> Anyway I could eventually develop my own converter for the Scribe
> notation. Is there a publicly accessible place that documents it?

The best way to develop such a converter is to start with the arm_form
code; it already has the lexical parser, and most of the semantic parser
that you need.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 12/05/2012 12:04, Stephen Leake escribi�:
> Manuel Collado<m.collado@domain.invalid>  writes:
>
>> My intention wasn't to develop the XML export facility myself, but to
>> develop post-processors, like you offer. It seems that the ARM
>> maintainers are considering to offer the XML export format sometime in
>> the future.
>
> You have misunderstood. Neither Randy (primary author of the ARM and
> arm_form Ada code), nor me (author of texinfo portion of arm_form Ada
> code) have said we will _do_ the XML export. We have said it would be
> good to have.

Sorry for my misunderstanding.

>
>> Anyway I could eventually develop my own converter for the Scribe
>> notation. Is there a publicly accessible place that documents it?
>
> The best way to develop such a converter is to start with the arm_form
> code; it already has the lexical parser, and most of the semantic parser
> that you need.

Thanks. Will try do contribute something on this line. But probably not 
in the immediate future.

Thanks again.
-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

"Nasser M. Abbasi" <nma@12000.org> writes:

> On 5/10/2012 2:21 AM, Dmitry A. Kazakov wrote:
>> On Wed, 9 May 2012 20:42:56 -0500, Randy Brukardt wrote:
>>
>>> Anyway, enough griping. I'm interested in concrete suggestions that can be
>>> implemented (not to promise that they would be). But be aware that I don't
>>> have much budget for RM work at this point, so I can't promise anything.
>>
>
>> I would lump everything in just one HTML page. Index and contents could be
>> in a separate frame, but not really necessary.
>>
>
> Why not use Latex? 

For what? 

If you mean "rewrite the original Scheme sources in Latex", that will
never happen.

1) read the Scheme (available at
http://www.stephe-leake.org/ada/arm_info-20120428-src.tar.gz)

2) there is a _lot_ more information in the Scheme than in a typical
Latex document. Three date versions: 1995, 2005, 2012. Two complexity
versions: ARM, Annotated ARM.

3) It would take way too much time to verify that the translation is
_perfect_

4) it would significantly change the layout.

> Then you get the full 30 years of latex scientific publication tools
> that Latex has, with all the indexing, table of contents,
> bibliography, page numbers, cross referneces, 

Already have all that. Yes, it was partly re-inventing the wheel, but it
was for good reasons.

It _might_ have made sense for someone very familiar with Latex, and
able to write complex Latex macros, to write the ARM in Latex starting
in 1983. But they didn't, and we have a working system, so there's no
reason to change it now.

> tables, figure, graphics, etc.. 

None of those appear in the current ARM; why are they needed?

> and zillions of latex packages that comes with it for free.

ditto.

> Then use Latex2html to convert everything to HTML. 

Have you actually compared the current HTML to Latex2html output? I
suspect the current HTML is much better (I have never used Latex2html; I
have used makeinfo to convert texinfo source to html; the result is
pretty horrible, although functional).

Is there an example of Latex2HTML output somewhere accessible? I'd like
to see it.

> Use pdflatex to generate PDF, generate .ps etc... all from the SAME
> plain text source files. see

Already have that; why does it need to change? Well, it might get
hyperlinks in the PDF; that would be good.

Note that you did not mention 'generate xml', which might be
interesting. Is there an xml backend for Latex? I have not heard of one.

I tried to add an arm_form option to generate Latex, so I could get PDF
with hyperlinks. It proved difficult; the semantic mismatch between the
Scheme and Latex was too large (which would also be a problem in manual
translation). I suspect it would be easier to generate PDF directly,
although that would mean implementing a paragraph fill algorithm.

Randy produces the PDF with Microsoft Word RTF as an intermediate; my
package produces PDF with texinfo as an intermediate. Randy's PDF is
much nicer, but neither has hyperlinks. 

> I do not know why any one will choose a different tool
> to publish anything. It is all there ;)

Time to learn! go read the Scheme source, and try to translate one small
file into Latex.

I am a big fan of Latex; I use it for all of my documents. But writing
new macros in it is a _pain_; the core language is just weird, most
existing macros are very poorly documented, and trying to read the
source code for them makes my head ache. You would need several new,
complex macros to attempt to translate the full ARM Scheme into Latex.

Since Randy writes both the Scheme and the arm_form Ada code that
processes, he can make it do _exactly_ what is needed, and can easily
understand the total system. That is a _Huge_ advantage over Latex.

arm_form was written for a very specific purpose; to format the various
versions of the ARM. It could be used for similar docs, such as the C++
standard (although the code might object :). There is no need for a
general purpose document prep system for the ARM.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Simon Wright]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> If you mean "rewrite the original Scheme sources in Latex", that will
> never happen.
>
> 1) read the Scheme (available at
> http://www.stephe-leake.org/ada/arm_info-20120428-src.tar.gz)
>
> 2) there is a _lot_ more information in the Scheme than in a typical
> Latex document. Three date versions: 1995, 2005, 2012. Two complexity
> versions: ARM, Annotated ARM.

"Scheme"? Randy says "a vaguely Scribe-like macro language".

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Simon Wright <simon@pushface.org> writes:

> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> If you mean "rewrite the original Scheme sources in Latex", that will
>> never happen.
>>
>> 1) read the Scheme (available at
>> http://www.stephe-leake.org/ada/arm_info-20120428-src.tar.gz)
>>
>> 2) there is a _lot_ more information in the Scheme than in a typical
>> Latex document. Three date versions: 1995, 2005, 2012. Two complexity
>> versions: ARM, Annotated ARM.
>
> "Scheme"? Randy says "a vaguely Scribe-like macro language".

Hmm. I don't know where I got Scheme from. It will be a while before my
memory gets fully edited (sigh). 

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message 
news:82d36bgcrz.fsf@stephe-leake.org...
...
>> tables, figure, graphics, etc..
>
> None of those appear in the current ARM; why are they needed?

Actually, the RM has a number of tables in Annex F and G; these are the most 
complex things to do. The HTML is correct, and the RTF works with specific 
versions of Microsoft Word, but nothing else (suggesting that it is not 
right in some subtle way, but I don't know what).

Arm_Form also supports .PNG and .JPEG graphics, we needed that for the ASIS 
standard. It only supports those formats because those are the only ones 
that are native to RTF. (Probably most people don't know that Microsoft Word 
converts almost all graphics to .PNG internally.)

...
> arm_form was written for a very specific purpose; to format the various
> versions of the ARM. It could be used for similar docs, such as the C++
> standard (although the code might object :). There is no need for a
> general purpose document prep system for the ARM.

And it has been: the ASIS standard, two versions of the Ada Rationale, and 
most of RR's documentation. (That's why I added the .MSM file to describe 
the document; originally the program could only produce the RM, which was 
rather limiting.)

                                       Randy.

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 03:42:56 +0200, Randy Brukardt <randy@rrsoftware.com>  
a écrit:

> "Jerrid Kimball" <jerrid@kimball.co> wrote in message
> news:joe7ad$ntc$1@munin.nbi.dk...
> ...
>> So--and this is directed at Randy also--feel free to stay away from
>> anything Oliver or I perceive as innovations on the front of community
>> building ad if you don't have useful discourse, ...
>
> As I said to Oliver, I don't want to see a fork in the (HTML) Standard,

I suggest to not focus that much on the HTML format, which is a  
publication format, and focus more on the source format. The source format  
is what matters, as a publication format is just a view among others.  
Don't believe the HTML format can be any kind of unique standard, that's  
more a convenience. On Windows, I tweaked it (which took me a long time)  
to turn it into MS‑HTMLHELP, which, on Windows, is much more useful and  
handy than plain HTML viewed in a browser (on Ubuntu, I still use the  
plain HTML format, as I've still not converted it to the DevHelp format).  
What the good publication format is, is platform and usage dependent,  
which is in turn, user dependent.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:

> On Windows, I tweaked it (which
> took me a long time)  to turn it into MS‑HTMLHELP, which, on Windows,
> is much more useful and  handy than plain HTML viewed in a browser 

If you took good notes, it would be good to incorporate those tweaks
into the arm_info tool. Producing a Windows-friendly version of the ARM
would be a Good Thing.

Please try it yourself, or send me your notes. Or your final output;
maybe I can reverse engineer it.

> (on Ubuntu, I still use the plain HTML format, as I've still not
> converted it to the DevHelp format). 

I've not heard of DevHelp. I found
http://ftp.gnome.org/pub/GNOME/sources/devhelp/3.0/ (via Wikipedia :).
It would be useful to add that to arm_info as well (less so than
MS-HTMLHELP). 

> What the good publication format is, is platform and usage dependent,
> which is in turn, user dependent.

That's very true. Which is why I added info to arm_form, and we should
add others, as well.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 13:57:24 +0200, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:

> "Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
>
>> On Windows, I tweaked it (which
>> took me a long time)  to turn it into MS‑HTMLHELP, which, on Windows,
>> is much more useful and  handy than plain HTML viewed in a browser
>
> If you took good notes, it would be good to incorporate those tweaks
> into the arm_info tool. Producing a Windows-friendly version of the ARM
> would be a Good Thing.
>
> Please try it yourself, or send me your notes. Or your final output;
> maybe I can reverse engineer it.

In few word, how I did it, was via JavaScript to have a straight away and  
easy access to the DOM of each HTML page. The JavaScript program returned  
me some data needed to create the tree and index. The JavaScript was  
embedded with simple <script href="...">, the page was loaded in a browser  
to execute the JavaScript, then the <script href="..."> was removed. I did  
it in turn for all pages, then merged all the data corresponding to each  
page, appropriately. Apart of that, CHM just expect plain HTML page (with  
some restriction), so the HTML pages was not changed, and only data  
extraction was needed, for some files required by he HTMLHELP compiler.

But please, wait, if I ever do what I said, generating a CHM would be much  
easier than that. I won't forget to tell here when something will be ready  
(just be patient, that's not planed for tomorrow, probably somewhere  
during the year).

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Georg Bauhaus]

On 11.05.12 14:55, Yannick Duchêne (Hibou57) wrote:

> But please, wait, if I ever do what I said, generating a CHM would be much
> easier than that. I won't forget to tell here when something will be ready
> (just be patient, that's not planed for tomorrow, probably somewhere during
> the year).

I think Aonix (Atego) used to have the LRM in (a precursor of) CHM,
Windows help.

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Randy Brukardt" <randy@rrsoftware.com> wrote in message 
news:jof6fe$7g2$1@munin.nbi.dk...
I said:

> Anyway, enough griping. I'm interested in concrete suggestions that can be 
> implemented (not to promise that they would be). But be aware that I don't 
> have much budget for RM work at this point, so I can't promise anything.

And I also should have said to send them to me via e-mail 
(agent@ada-auth.org), so I can easily file them permanently and put them 
onto my todo lists. If I see any wonderful ideas here I'll probably scoop 
them up, but I'm not likely to do that with the majority of them (why make 
more work for myself?).

                                      Randy. 

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Wed, 09 May 2012 16:09:10 +0200, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:

> On Wed, 09 May 2012 15:56:32 +0200, Georg Bauhaus wrote:
>
>> On 09.05.12 15:00, Dmitry A. Kazakov wrote:
>>> On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:
>>>
>>>> I think XML is not good for math.
>>>
>>> XML is not good for anything.  I don't care about Web but in  
>>> automation it
>>> becomes a growing problem that precious bandwidth and human resources  
>>> are
>>> spent on chewing XML mess.
>>
>> Writing math papers and making data traveling automation networks
>> seem rather different use cases.
>
> Yes, though XML is usually advocated as a universal solution for
> everything.

Not for everything: for when a standard structured serialization is really  
better (and that's often the case).

Then, XML does not came alone, it comes with XSLT, XPath, XQuery and  
XProc, although these do not apply directly to the serialized data, but to  
the unserialized data tree (for XProc, as a pure pipelined stream). It  
also comes with standard attributes (even outside of any document type  
definition), like xml:id, xml:lang, whose content are as much formalized  
as XML is.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Thu, 10 May 2012 02:57:32 +0200, Yannick Duch�ne (Hibou57) wrote:

> Le Wed, 09 May 2012 16:09:10 +0200, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a �crit:
> 
>> On Wed, 09 May 2012 15:56:32 +0200, Georg Bauhaus wrote:
>>
>>> On 09.05.12 15:00, Dmitry A. Kazakov wrote:
>>>> On Wed, 09 May 2012 07:06:06 -0500, Nasser M. Abbasi wrote:
>>>>
>>>>> I think XML is not good for math.
>>>>
>>>> XML is not good for anything.  I don't care about Web but in automation it
>>>> becomes a growing problem that precious bandwidth and human resources  
>>>> are spent on chewing XML mess.
>>>
>>> Writing math papers and making data traveling automation networks
>>> seem rather different use cases.
>>
>> Yes, though XML is usually advocated as a universal solution for
>> everything.
> 
> Not for everything: for when a standard structured serialization is really  
> better (and that's often the case).

I don't know what "standard structured serialization" is. But XML is bad
for serialization (if persistence meant). It is awful to describe
structures (because it lacks means to handle dependencies, referential
semantics, decomposition means, whatever abstraction power, types, semantic
checks present in any language since FORTRAN IV etc. As a "language" it is
really retarded.)

> Then, XML does not came alone, it comes with XSLT, XPath, XQuery and  
> XProc,

Which also reveals much about its usability. You don't need any tools to
handle a *usable* thing.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 09:13:56 +0200, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:
>> Not for everything: for when a standard structured serialization is  
>> really
>> better (and that's often the case).
>
> I don't know what "standard structured serialization" is.
May be my English is not so good, sorry :P I meant, standard serialization  
for structured data, structured as a tree, and potentially as a graph, via  
IDs and IDREFs.

> But XML is bad
> for serialization (if persistence meant). It is awful to describe
> structures (because it lacks means to handle dependencies, referential
> semantics, decomposition means, whatever abstraction power, types,  
> semantic
> checks present in any language since FORTRAN IV etc. As a "language" it  
> is
> really retarded.)

That's the role of document type definitions, which can be either DTD (the  
legacy and most widely used solution, which is inherited from the SGML  
era), or XSD (the most standard one along with DTD) or RNG and Schematron.

>> Then, XML does not came alone, it comes with XSLT, XPath, XQuery and
>> XProc,
>
> Which also reveals much about its usability. You don't need any tools to
> handle a *usable* thing.

No? You don't need tool to check Ada source legality?


-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Thu, 10 May 2012 15:37:37 +0200, Yannick Duch�ne (Hibou57) wrote:

> Le Thu, 10 May 2012 09:13:56 +0200, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a �crit:
>>> Not for everything: for when a standard structured serialization is really
>>> better (and that's often the case).
>>
>> I don't know what "standard structured serialization" is.
> May be my English is not so good, sorry :P I meant, standard serialization  
> for structured data, structured as a tree, and potentially as a graph, via  
> IDs and IDREFs.

Yes, XML would be a catastrophic data base management system. 

>> Which also reveals much about its usability. You don't need any tools to
>> handle a *usable* thing.
> 
> No? You don't need tool to check Ada source legality?

Never used that thing. Ada compilers are validated. In doubt I rather ask
our language lawyers here.

BTW, XML is ever worse that just that. The "legality" you are talking about
is merely stupid syntax checks, necessary because guys were unable to get
the syntax right. It is not even close to what we understand under legality
for Ada programs. XML is meaningless as a programming language. It does not
define any semantics beyond counting opening and closing brackets. You can
stuff any rubbish into XML. It is a presentation format, pure waste of
bandwidth, absolutely useless.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 17:02:30 +0200, Dmitry A. Kazakov  
<mailbox@dmitry-kazakov.de> a écrit:
>> No? You don't need tool to check Ada source legality?
>
> Never used that thing. Ada compilers are validated. In doubt I rather ask
> our language lawyers here.

What's a compiler if not a tool? You just confirmed the assertion.

> BTW, XML is ever worse that just that. The "legality" you are talking  
> about
> is merely stupid syntax checks,

What you are talking about here, is not validity, that's well‑formedness.  
Both well‑formedness and validity are formalized by the XML specification,  
and are different levels and requirements (there are others too), just  
like you have static‑constraint and dynamic‑constraint with Ada.

> necessary because guys were unable to get
> the syntax right.

Sorry, although I enjoy a lot your analyses about Ada, when you talk about  
XML, your analyses are stupids :P

Just forget about XML. If you don't like it, that's probably because you  
never encountered a case where you need it (as much as because your seems  
to be not aware of document authoring matters, as XML is not only used for  
hard‑data serialization) and it as a standard.

Nevertheless, keep in mind that the word “standard” is emphasized a lot  
here ;) And with the word ”standard” comes the words ”interoperability”.

Topic closed for me, I won't argue anymore, not the place for that, just  
that I didn't want to left such assertions without an answer.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Dmitry A. Kazakov]

On Thu, 10 May 2012 17:32:41 +0200, Yannick Duchêne (Hibou57) wrote:

> Le Thu, 10 May 2012 17:02:30 +0200, Dmitry A. Kazakov  
> <mailbox@dmitry-kazakov.de> a écrit:
>>> No? You don't need tool to check Ada source legality?
>>
>> Never used that thing. Ada compilers are validated. In doubt I rather ask
>> our language lawyers here.
> 
> What's a compiler if not a tool?

No, it is not. Tools are used to assist a programmer, user, maintainer etc
role player, in his work. As such tools are superfluous, non-functional.
Compiler is absolutely necessary. If you want an analogy, XML parser is
necessary when somebody was foolish enough to mandate use of XML.

> Just forget about XML. If you don't like it, that's probably because you  
> never encountered a case where you need it (as much as because your seems  
> to be not aware of document authoring matters,

So, the claim is that XML is good for authoring documents? Come on, give me
a break!

> as XML is not only used for hard‑data serialization) and it as a standard.

Being standard does not make anything good. Standard is not a function.

> Nevertheless, keep in mind that the word “standard” is emphasized a lot  
> here ;)

Not prior to:

"Ada is a programming language designed to support the construction of
long-lived, highly reliable software systems."

> And with the word ”standard” comes the words ”interoperability”.

Interoperability between which parties, solving which problems?

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Ada Reference Manual 2012 in info format

[Oliver Kleinke]

> BTW, XML is ever worse that just that. The "legality" you are talking
> about is merely stupid syntax checks, necessary because guys were
> unable to get the syntax right. It is not even close to what we
> understand under legality for Ada programs. XML is meaningless as a
> programming language. It does not define any semantics beyond
> counting opening and closing brackets. You can stuff any rubbish into
> XML. It is a presentation format, pure waste of bandwidth, absolutely
> useless.
> 

Most (parsing-)legality problems won't ever arise in XML because of the
way it was designed. XML is no programming language. Moreover more
complex rules can be enforced using XSD.[1][2]
Obviously you know diddly-squat about XML and XML-related technologies,
therefore you should either brush up on your knowledge or stay mum.
Apart from that your points are totally inept and bizarre.

--
[1] - http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/
[2] - http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message 
news:20120509131736.63c924c8@vostro...
> Am Thu, 3 May 2012 18:25:53 -0500
>> If you do spend time making an alternative version of the Standard, I
>> strongly recommend that you do so by modifying the ARM_Formatter
>> tool. That way, you can convert future versions of the Standard to
>> your format easily (if it is a by-hand conversion, it will become
>> obsolete far quicker than you realize and then you'll either have to
>> do it all again or forget it). And that would also allow the
>> alternate version to be used on the Rationale and other standards
>> documents, if that is appropriate someday. (That's what Stephen Leake
>> did with the "info" version.)
>>
> you have to realize that design and looks do have a function beyond
> fancy, usability for example. I think you derailed the conversation for
> your own purpose of defending the RM from change. "malware-laden ads",
> "run god-knows-what on your computer", "Start Menu in Windows 8" --
> these are cheesy strawman arguments and it sounds like you are accusing
> Jerrid that this is what he has in mind.

Well, let me defend myself simply by saying 95% of change is bad. At best, 
it wastes your time and energies, and much of the time is worse than that, 
by preventing you from doing valuable things at all. The above supposedly 
"straw-men" are just examples of that.

I'd never say that *all* change is bad (I get lots of use out of GPS and 
cell phone devices, neither of which [practically] existed when I was in 
college), but would argue that proving the value of change is on those that 
would try to make it -- my default position is that it is bad. Feel free to 
prove to me otherwise.

As far as usablity goes, I've already said that I'd like to upgrade the 
navigation facilities of the RM. If someone has suggestions for doing that, 
I'd love to see them, especially if they can be relatively easily added to 
the existing tools. But beyond that, I think you will find it very difficult 
to "modernize" the RM without damaging its usability, because so many things 
are constrained -- you can't change the fonts significantly (as these are 
significant in the understanding), you can't change the format much 
(damaging to examples and other "preformatted" layout), and you can't 
separate it into smaller chunks (because there is too much 
interrelationships between adjacent text, much of it makes no sense by 
itself).

To really make the RM more "usable", you'd have to start over with the 
organization of the contents, and that's neither practical (way too much 
work) nor possible (it would no longer reflect the Standard, which is kinda 
the point).

...
> Providing a modern HTML version does not exclude the possibility to
> provide a more 'compatible' version, so don't be so obstinate. :-)

I'd much rather avoid a fork if at all possible, in large part because 
people use the RM to determine "the rules" and ultimately to reports to both 
the ARG and to implementers. If there are RM versions out there that make 
that difficult, then that's harmful. (And I'd rather that Google searches 
land on the "official" RM, which makes it best that there aren't competing 
versions out there.)

Note that I have absolutely no objections to putting the RM into *other* 
formats (as Stephen did for "info"), because that just makes Ada more 
adaptable -- which is not a bad thing.

                                      Randy.

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message 
news:20120509131736.63c924c8@vostro...
>...
> Honestly, you should consider converting the sources to a more appropriate 
> format.

The sources are still in the original Scribe format used by Jean Ichbiah's 
team back in the 1970s. Some sort of conversion (without losing any 
information) would be pretty expensive, even if it could be automated. 
(Preserving the comments in the files would be hard, for instance, as the 
formatter discards them immediately.)

...
> Also, the
> way the Formatter sources are provided sucks major -- cvsweb, you have
> to click around a lot until you have a complete set of files plus some
> of the HEAD versions have been broken.

There is are ZIP files with the complete set of sources, both to the tools 
and the RM (Scribe-like) source. But I think the links disappeared, because 
I can't find them. (Something else for the todo list.)

Not sure what you mean by the "HEAD versions have been broken", because this 
is a frequently updated copy of the repository on my computer, and I'm 
pretty sure there is no broken source on my computer. :-) If you have any 
examples, I'll look into them.

Unimportant aside: The repository hasn't used "cvsweb" for a number of 
years; it's actually implemented in Ada (I was not interested in running 
unknown Perl code on my server!); it just emulates the "cvsweb" links 
because I didn't want to break anybodies existing links into the repository 
(and there are a lot of them, especially in downloaded copies of the Ada 
RM). It's smarter than "cvsweb" was, especially when displaying AIs. It 
could be improved further, but I'd need a good idea that wouldn't break 
links (which admittedly is very limiting).

                                   Randy.

Re: Ada Reference Manual 2012 in info format

[Oliver Kleinke]

Am Wed, 9 May 2012 20:54:32 -0500
schrieb "Randy Brukardt" <randy@rrsoftware.com>:

> "Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message 
> news:20120509131736.63c924c8@vostro...
> >...
> > Honestly, you should consider converting the sources to a more
> > appropriate format.
> 
> The sources are still in the original Scribe format used by Jean
> Ichbiah's team back in the 1970s. Some sort of conversion (without
> losing any information) would be pretty expensive, even if it could
> be automated. (Preserving the comments in the files would be hard,
> for instance, as the formatter discards them immediately.)

I concur; however, it might still be worth it in the long run. Maybe it
would suffice to progressively make adjustments to the current format,
for example converting some of the style-markup into semantic-markup
(bold to keyword where it is appropriate, &c.)

> ...
> > Also, the
> > way the Formatter sources are provided sucks major -- cvsweb, you
> > have to click around a lot until you have a complete set of files
> > plus some of the HEAD versions have been broken.
> 
> There is are ZIP files with the complete set of sources, both to the
> tools and the RM (Scribe-like) source. But I think the links
> disappeared, because I can't find them. (Something else for the todo
> list.)

I did not find any of ZIP files, if I overlooked them it was of course
my mistake and I shall withdraw my accusations.

> Not sure what you mean by the "HEAD versions have been broken",
> because this is a frequently updated copy of the repository on my
> computer, and I'm pretty sure there is no broken source on my
> computer. :-) If you have any examples, I'll look into them.

With broken I meant inconsistencies. I'll tip you off if I encounter
that problem again ;-)


Oliver

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message 
news:20120511043604.344c13a8@vostro...
> Am Wed, 9 May 2012 20:54:32 -0500
> schrieb "Randy Brukardt" <randy@rrsoftware.com>:
>
>> "Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message
>> news:20120509131736.63c924c8@vostro...
>> >...
>> > Honestly, you should consider converting the sources to a more
>> > appropriate format.
>>
>> The sources are still in the original Scribe format used by Jean
>> Ichbiah's team back in the 1970s. Some sort of conversion (without
>> losing any information) would be pretty expensive, even if it could
>> be automated. (Preserving the comments in the files would be hard,
>> for instance, as the formatter discards them immediately.)
>
> I concur; however, it might still be worth it in the long run. Maybe it
> would suffice to progressively make adjustments to the current format,
> for example converting some of the style-markup into semantic-markup
> (bold to keyword where it is appropriate, &c.)

The original sources were somewhat inconsistent about this. I try to use the 
semantic markup whenever possible (@key, @nt, @syni, @examcom, etc. --  
keyword, non-terminal, syntax italics [the prefixes to syntax terms, like 
@SynI<exception_>@nt<name>], and example comment respectively) but I 
probably forget from time-to-time like any human. And there probably are a 
few others that could have been defined.

>> ...
>> There is are ZIP files with the complete set of sources, both to the
>> tools and the RM (Scribe-like) source. But I think the links
>> disappeared, because I can't find them. (Something else for the todo
>> list.)
>
> I did not find any of ZIP files, if I overlooked them it was of course
> my mistake and I shall withdraw my accusations.

I didn't find them, either, which is weird because my batch files make them 
every time I post a new version of the Standard. Not sure why links to them 
never got added to the web site. I've added that to me "todo" list.

                                 Randy.


>> Not sure what you mean by the "HEAD versions have been broken",
>> because this is a frequently updated copy of the repository on my
>> computer, and I'm pretty sure there is no broken source on my
>> computer. :-) If you have any examples, I'll look into them.
>
> With broken I meant inconsistencies. I'll tip you off if I encounter
> that problem again ;-)
>
>
> Oliver
> 

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Oliver Kleinke <oliver.kleinke@c-01a.de> writes:

> I am writing an XML extension to the formatter. 

Excellent!

> It's not finished yet but does already look promising. Why XML?
> Because it's easily transformable into nearly every other format
> (Original Source format, plain-text, HTML, PDF, DocBook, DITA, info,
> SQL inserts, you name it..) using XSL (I'm talking XSLT + XSL-FO). 

Sounds like a good idea; I'd really like to have a PDF with full
hyperlinks. 

> A major problem of the formatter/RM sources is that they only provide
> partial semantic information about the contents, that IS 1995-style.

What, exactly, is missing? Can you give an example?

If you are trying to translate the Scheme into XML so that the XML
contains _all_ of the information in the Scheme, and saying that
arm_form does not provide the facilities to do that, then you are
probably right; arm_form was not designed to do that. arm_form was
designed to produce readable output formats from the Scheme; the output
formats contain far less information than the Scheme.

If you are saying the Scheme does not have all the information you want,
then I don't understand what is missing.

> Honestly, you should consider converting the sources to a more
> appropriate format. 

There are a _lot_ of requirements on the format. A big one is
"don't lose any history". That's _very_ hard to satisfy in a totally new
format! 

Another big one is "don't waste Randy's time"; it takes time to learn
any new format. It takes _far_ more time to verify that the translation
is _perfect_.

You have not provided any solid rationale for considering such a major
change.

Just be glad the source is machine readable; it might have been in Word,
or Adobe Framemaker!

> Also, the way the Formatter sources are provided sucks major --
> cvsweb, you have to click around a lot until you have a complete set
> of files plus some of the HEAD versions have been broken.

Yes, but that's why I provide a .tar.gz of the full source: 

http://www.stephe-leake.org/ada/arm_info-20120428-src.tar.gz

http://www.stephe-leake.org/ada/arm.html

In Randy's defense, any more sophisticated access would require a hole
in his firewall. I much prefer that Randy spend his time working on ARG
stuff, and maintaining AdaIC.org, than chasing problems due to holes in
firewalls! Anyone doing this work should be able to cope, or build
on my work. It's not like there are hundreds of us!

> Providing a modern HTML version does not exclude the possibility to
> provide a more 'compatible' version, 

You have yet to define what you mean by either "modern" or "compatible",
either by example or description.

It's getting hard to be patient!

> so don't be so obstinate. :-)

I'm seeing far more obstinate behavior from you than from Randy.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Oliver Kleinke]

Am Thu, 10 May 2012 11:11:25 +0100
schrieb Stephen Leake <stephen_leake@stephe-leake.org>:

> > A major problem of the formatter/RM sources is that they only
> > provide partial semantic information about the contents, that IS
> > 1995-style.
> 
> What, exactly, is missing? Can you give an example?

I'll provide one example:

when ARM_Output.Small =>
   if Indent = 0 then
      return "Small";
   elsif Indent = 1 then
      return "Notes";
   elsif Indent = 2 then
      return "Annotations";

As you can easily see the two style attributes 'Small' (paragraph/header
style) and Indent (paragraph indentation) are used to determine the
semantics of the paragraph's contents. So if you are a bright guy,
you'll figure out what's bad about it.

More semantic markup would also facilitate the extraction of information
from the RM, e.g. to feed the data into an IDE (Manuel Collado pointed
that out).


> In Randy's defense, any more sophisticated access would require a hole
> in his firewall.

lol, k

> > Providing a modern HTML version does not exclude the possibility to
> > provide a more 'compatible' version, 
> 
> You have yet to define what you mean by either "modern" or
> "compatible", either by example or description.

For instance the paragraphs have no anchors, thus the possibility of
deep-linking is limited. The Index has neither anchors for the letters
nor links to them at the top. I can think of a lot more.

> It's getting hard to be patient!

The limits of your imagination are none of my concerns.

> > so don't be so obstinate. :-)
> 
> I'm seeing far more obstinate behavior from you than from Randy.

Is that so?

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 04:07:10 +0200, Oliver Kleinke  
<oliver.kleinke@c-01a.de> a écrit:
>> In Randy's defense, any more sophisticated access would require a hole
>> in his firewall.
>
> lol, k
>
>> > Providing a modern HTML version does not exclude the possibility to
>> > provide a more 'compatible' version,
>>
>> You have yet to define what you mean by either "modern" or
>> "compatible", either by example or description.
>
> For instance the paragraphs have no anchors, thus the possibility of
> deep-linking is limited. The Index has neither anchors for the letters
> nor links to them at the top. I can think of a lot more.

In Randy's defense too, the anchor matter is more a browser matter than an  
Ada‑RM source matter. Even in DocBook and others, you don't give  
everything an identifier or name. You give one for some context, and then  
access more specific components of that context with XPath and its  
expressions. Ex. if browser would support it, you could access the nth  
paragraph of a given chapter. Unfortunately, browsers don't. To give  
anchors to everything would be too much.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Oliver Kleinke]

> > For instance the paragraphs have no anchors, thus the possibility of
> > deep-linking is limited. The Index has neither anchors for the
> > letters nor links to them at the top. I can think of a lot more.
> 
> In Randy's defense too, the anchor matter is more a browser matter
> than an Ada‑RM source matter. Even in DocBook and others, you don't
> give everything an identifier or name. You give one for some context,
> and then access more specific components of that context with XPath
> and its expressions. Ex. if browser would support it, you could
> access the nth paragraph of a given chapter. Unfortunately, browsers
> don't. To give anchors to everything would be too much.
> 

What browser matter? What has DocBook to do with that? I can put my
anchors where I like them to be. XPath in URIs is far from
practicability. You will be free to modify the XSLT-sheet to your
liking, if my anchor-placement does not suit you.

Oliver

Suggestion for RM HTML formatter extension (Was: Ada Reference Manual 2012 in info format)

[Jacob Sparre Andersen]

Yannick Duch�ne wrote:

> To give anchors to everything would be too much.

Considering how often we refer to specific RM paragraphs here on CLA, I
think it would be worthwhile to be able to write links pointing to
specific paragraphs.

If I could write <http://www.adaic.org/rm05/9.7.3#6> and people would
end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
would be much easier than linking to the whole section and then writing
that people have to scroll down to paragraph 6.

Greetings,

Jacob
-- 
"Sleep is just a cheap substitute for coffee"

Re: Suggestion for RM HTML formatter extension (Was: Ada Reference Manual 2012 in info format)

[Martin]

On Friday, May 11, 2012 8:51:30 AM UTC+1, Jacob Sparre Andersen wrote:
> Yannick Duchêne wrote:
> 
> > To give anchors to everything would be too much.
> 
> Considering how often we refer to specific RM paragraphs here on CLA, I
> think it would be worthwhile to be able to write links pointing to
> specific paragraphs.
> 
> If I could write <http://www.adaic.org/rm05/9.7.3#6> and people would
> end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
> would be much easier than linking to the whole section and then writing
> that people have to scroll down to paragraph 6.
> 
> Greetings,
> 
> Jacob
> -- 
> "Sleep is just a cheap substitute for coffee"

+1 - great idea

Re: Suggestion for RM HTML formatter extension

[Simon Wright]

[-- Attachment #1: Type: text/plain, Size: 858 bytes --]

Jacob Sparre Andersen <sparre@nbi.dk> writes:

> Yannick Duchêne wrote:
>
>> To give anchors to everything would be too much.
>
> Considering how often we refer to specific RM paragraphs here on CLA, I
> think it would be worthwhile to be able to write links pointing to
> specific paragraphs.
>
> If I could write <http://www.adaic.org/rm05/9.7.3#6> and people would
> end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
> would be much easier than linking to the whole section and then writing
> that people have to scroll down to paragraph 6.

I'd have thought that would be straightforward enough .. the paragraph
numbers are in a div with class paranum. A simple patch means I can
write <RM-A-3-2.html#p13/2> for para 13/2 of the 2005 manual (I'm not at
all sure of the legality of that slash, but Safari and Chrome are happy!!).


[-- Attachment #2: Patch --]
[-- Type: text/plain, Size: 844 bytes --]

diff -r 61202be49b9e progs/arm_html.adb
--- a/progs/arm_html.adb	Thu May 10 16:59:13 2012 +0100
+++ b/progs/arm_html.adb	Fri May 11 16:31:24 2012 +0100
@@ -2345,7 +2345,11 @@
 	    if Number /= "" then -- Has paragraph number.

 		Paranum_Used := True;

 	        Ada.Text_IO.Put (Output_Object.Output_File, "<div class=""paranum"">");

+                Ada.Text_IO.Put (Output_Object.Output_File, "<a name=""p");

 	        Ada.Text_IO.Put (Output_Object.Output_File, Number);

+                Ada.Text_IO.Put (Output_Object.Output_File, """>");

+	        Ada.Text_IO.Put (Output_Object.Output_File, Number);

+                Ada.Text_IO.Put (Output_Object.Output_File, "</a>");

 	        Ada.Text_IO.Put_Line (Output_Object.Output_File, "</div>");

 	        Output_Object.Char_Count := 0;

 	        Output_Object.Disp_Char_Count := 0;

Re: Suggestion for RM HTML formatter extension

[Simon Wright]

Simon Wright <simon@pushface.org> writes:

> I'd have thought that would be straightforward enough .. the paragraph
> numbers are in a div with class paranum. A simple patch means I can
> write <RM-A-3-2.html#p13/2> for para 13/2 of the 2005 manual (I'm not at
> all sure of the legality of that slash, but Safari and Chrome are happy!!).

Try http://dl.dropbox.com/u/34783908/ARM05/RM-A-3-2.html#p13/2 ...

Re: Suggestion for RM HTML formatter extension

[Jacob Sparre Andersen]

Simon Wright wrote:

> Try http://dl.dropbox.com/u/34783908/ARM05/RM-A-3-2.html#p13/2 ...

Great.  Exactly what I meant.

Jacob
-- 
"The pictures on radio are always so much better than those on TV."
                                       -- Pratchet, Stewart & Cohen

Re: Suggestion for RM HTML formatter extension

[Ludovic Brenta]

Simon Wright <simon@pushface.org> writes:
> Simon Wright <simon@pushface.org> writes:
>
>> I'd have thought that would be straightforward enough .. the paragraph
>> numbers are in a div with class paranum. A simple patch means I can
>> write <RM-A-3-2.html#p13/2> for para 13/2 of the 2005 manual (I'm not at
>> all sure of the legality of that slash, but Safari and Chrome are happy!!).
>
> Try http://dl.dropbox.com/u/34783908/ARM05/RM-A-3-2.html#p13/2 ...

Iceweasel here is happy too :)

-- 
Ludovic Brenta.

Re: Suggestion for RM HTML formatter extension

[Simon Wright]

Simon Wright <simon@pushface.org> writes:

> A simple patch

That patch is actually incomplete (there's another case I missed, which
I think would be invoked for a different output selection):

diff -r 61202be49b9e progs/arm_html.adb
--- a/progs/arm_html.adb	Thu May 10 16:59:13 2012 +0100
+++ b/progs/arm_html.adb	Fri May 11 16:57:39 2012 +0100
@@ -2254,7 +2254,11 @@
 		Paranum_Used := True;
 		Ada.Text_IO.Put (Output_Object.Output_File, "<div class=""paranum"">");
 	        Ada.Text_IO.Put (Output_Object.Output_File, "<font size=-2>");
+                Ada.Text_IO.Put (Output_Object.Output_File, "<a name=""p");
 	        Ada.Text_IO.Put (Output_Object.Output_File, Number);
+                Ada.Text_IO.Put (Output_Object.Output_File, """>");
+	        Ada.Text_IO.Put (Output_Object.Output_File, Number);
+                Ada.Text_IO.Put (Output_Object.Output_File, "</a>");
 	        Ada.Text_IO.Put (Output_Object.Output_File, "</font>");
 	        Ada.Text_IO.Put_Line (Output_Object.Output_File, "</div>");
 	        Output_Object.Char_Count := 0;
@@ -2345,7 +2349,11 @@
 	    if Number /= "" then -- Has paragraph number.
 		Paranum_Used := True;
 	        Ada.Text_IO.Put (Output_Object.Output_File, "<div class=""paranum"">");
+                Ada.Text_IO.Put (Output_Object.Output_File, "<a name=""p");
 	        Ada.Text_IO.Put (Output_Object.Output_File, Number);
+                Ada.Text_IO.Put (Output_Object.Output_File, """>");
+	        Ada.Text_IO.Put (Output_Object.Output_File, Number);
+                Ada.Text_IO.Put (Output_Object.Output_File, "</a>");
 	        Ada.Text_IO.Put_Line (Output_Object.Output_File, "</div>");
 	        Output_Object.Char_Count := 0;
 	        Output_Object.Disp_Char_Count := 0;

Re: Suggestion for RM HTML formatter extension

[Stephen Leake]

> Simon Wright <simon@pushface.org> writes:
>
>> A simple patch

Excellent!

Now we have to work out with Randy how to get this patch into the
official sources ...

I'll add it to my version, which I diff with Randy's periodically.

It's small enough that copyright assignment need not be a concern (I
assume you have no objection to GPL 3?).

I'll have to think about whether this is worth adding to the info
version; texinfo has anchor browser, but I don't think external links
can use them effectively.

-- 
-- Stephe

Re: Suggestion for RM HTML formatter extension

[Simon Wright]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

>> Simon Wright <simon@pushface.org> writes:
>>
>>> A simple patch

> It's small enough that copyright assignment need not be a concern (I
> assume you have no objection to GPL 3?).

That's fine.

rm-9.7.3.html, which contains one of the paragraph "numbers" I was
worried about (1/2) validates OK at
http://www.w3schools.com/web/web_validate.asp with a couple of warnings
about character encodings that may be worth looking into.

Re: Suggestion for RM HTML formatter extension

[Manuel Collado]

El 11/05/2012 17:32, Simon Wright escribió:
> Jacob Sparre Andersen<sparre@nbi.dk>  writes:
>>...
>> If I could write<http://www.adaic.org/rm05/9.7.3#6>  and people would
>> end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
>> would be much easier than linking to the whole section and then writing
>> that people have to scroll down to paragraph 6.
>
> I'd have thought that would be straightforward enough .. the paragraph
> numbers are in a div with class paranum. A simple patch means I can
> write<RM-A-3-2.html#p13/2>  for para 13/2 of the 2005 manual (I'm not at
> all sure of the legality of that slash, but Safari and Chrome are happy!!).

Is seems that p13/2 as a "name" target is legal in HTML, but not in 
XHTML. In addition, IIUC the use of the "name" attribute is deprecated 
in favor of the "id" one, and XHTML5 even has dropped it.

"id" values don't allow slashes. But slashes could be easily converted 
to hyphens or underscores, if browser standard compliance really 
matters. So we could write <RM-A-3-2.html#p13-2>, for instance

In addition, if old and new browsers have to be supported, I believe it 
is also possible to have both "id" and "name" target attributes with 
exactly the same, duplicated value.

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Suggestion for RM HTML formatter extension

[Simon Wright]

Manuel Collado <m.collado@domain.invalid> writes:

> El 11/05/2012 17:32, Simon Wright escribió:
>> Jacob Sparre Andersen<sparre@nbi.dk>  writes:
>>>...
>>> If I could write<http://www.adaic.org/rm05/9.7.3#6>  and people would
>>> end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
>>> would be much easier than linking to the whole section and then writing
>>> that people have to scroll down to paragraph 6.
>>
>> I'd have thought that would be straightforward enough .. the paragraph
>> numbers are in a div with class paranum. A simple patch means I can
>> write<RM-A-3-2.html#p13/2>  for para 13/2 of the 2005 manual (I'm not at
>> all sure of the legality of that slash, but Safari and Chrome are happy!!).
>
> Is seems that p13/2 as a "name" target is legal in HTML, but not in
> XHTML. In addition, IIUC the use of the "name" attribute is deprecated
> in favor of the "id" one, and XHTML5 even has dropped it.
>
> "id" values don't allow slashes. But slashes could be easily converted
> to hyphens or underscores, if browser standard compliance really
> matters. So we could write <RM-A-3-2.html#p13-2>, for instance
>
> In addition, if old and new browsers have to be supported, I believe
> it is also possible to have both "id" and "name" target attributes
> with exactly the same, duplicated value.

The currently-generated doctype (for ARM05, I suspect it might be
different for other possibilities) is

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">

so XHTML compliance isn't strictly an issue. No bad thing, of course.

I see that Jacob's original request didn't ask for my 'p', so I should
probably have left it off.

The cross-references in the current ARM appear to use generated names
like I7733, need to avoid clashes!

Re: Suggestion for RM HTML formatter extension

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2434 bytes --]

"Manuel Collado" <m.collado@domain.invalid> wrote in message 
news:joqqmr$ki4$1@speranza.aioe.org...
> El 11/05/2012 17:32, Simon Wright escribi�:
>> Jacob Sparre Andersen<sparre@nbi.dk>  writes:
>>>...
>>> If I could write<http://www.adaic.org/rm05/9.7.3#6>  and people would
>>> end up at paragraph 6 in section 9.7.3 of the Ada05 reference manual, it
>>> would be much easier than linking to the whole section and then writing
>>> that people have to scroll down to paragraph 6.
>>
>> I'd have thought that would be straightforward enough .. the paragraph
>> numbers are in a div with class paranum. A simple patch means I can
>> write<RM-A-3-2.html#p13/2>  for para 13/2 of the 2005 manual (I'm not at
>> all sure of the legality of that slash, but Safari and Chrome are 
>> happy!!).
>
> Is seems that p13/2 as a "name" target is legal in HTML, but not in XHTML. 
> In addition, IIUC the use of the "name" attribute is deprecated in favor 
> of the "id" one, and XHTML5 even has dropped it.
>
> "id" values don't allow slashes. But slashes could be easily converted to 
> hyphens or underscores, if browser standard compliance really matters. So 
> we could write <RM-A-3-2.html#p13-2>, for instance

We don't need the slashes at all, since that just a version indicator, and 
the root path specifies the version of the document anyway. I was just going 
to strip them when I added them to ARM_Form. That's especially valuable 
since these versions are much more likely to change than the paraagraph 
numbers themselves, so it would make the links more resilient to change 
(important for working versions of the Standard).

I was more worried about the periods (which are not optional). They could be 
converted to something else, but then the correspondence between the anchor 
name and the paragraph number would not be as obvious, which would possibly 
hurt the usage (when people want to hand-create these links - which seems to 
be the main benefit of the idea).

> In addition, if old and new browsers have to be supported, I believe it is 
> also possible to have both "id" and "name" target attributes with exactly 
> the same, duplicated value.

That would seem to be necessary (I've only used "name" because older 
browsers don't support "id" - I rather doubt any browsers are going to be 
dropping support for it anytime soon because it is widely used).

                                                 Randy.

Re: Suggestion for RM HTML formatter extension

[Georg Bauhaus]

On 15.05.12 09:02, Randy Brukardt wrote:
> "Manuel Collado"<m.collado@domain.invalid>  wrote in message

>> Is seems that p13/2 as a "name" target is legal in HTML, but not in XHTML.
>> In addition, IIUC the use of the "name" attribute is deprecated in favor
>> of the "id" one, and XHTML5 even has dropped it.
>>
>> "id" values don't allow slashes. But slashes could be easily converted to
>> hyphens or underscores, if browser standard compliance really matters. So
>> we could write<RM-A-3-2.html#p13-2>, for instance
>
...
> I was more worried about the periods (which are not optional). They could be
> converted to something else, but then the correspondence between the anchor
> name and the paragraph number would not be as obvious, which would possibly
> hurt the usage (when people want to hand-create these links - which seems to
> be the main benefit of the idea).
>
>> In addition, if old and new browsers have to be supported, I believe it is
>> also possible to have both "id" and "name" target attributes with exactly
>> the same, duplicated value.
>
> That would seem to be necessary (I've only used "name" because older
> browsers don't support "id" - I rather doubt any browsers are going to be
> dropping support for it anytime soon because it is widely used).

Just for reference, the production for [VC:ID] of XML
includes '.' and '-' in the suffix of NameStartChar (NameChar)*.[1]

The CSS grammar, however, doesn't include '.' in its nmchar.[2]
Otherwise one couln't write style sheet rules that select with
elementname.classsname.

But there is a workaround in CSS for incorrect elementname#id.with.dots.
One writes elementname[id="id.with.dots"]. So a combination of '.' and '-'
would be standards compliant, and still practical.

__
[1] http://www.w3.org/TR/REC-xml/#NT-Name
[2] http://www.w3.org/TR/css3-syntax/#grammar

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:

> In Randy's defense too, the anchor matter is more a browser matter
> than an Ada‑RM source matter. Even in DocBook and others, you don't
> give  everything an identifier or name. You give one for some context,
> and then  access more specific components of that context with XPath
> and its  expressions. Ex. if browser would support it, you could
> access the nth  paragraph of a given chapter. Unfortunately, browsers
> don't. To give  anchors to everything would be too much.

What is the metric for "too much"?

If we were writing the source by hand, then inserting anchors everywhere
would be tedious, and thus "too much". 

But adding a few lines of code to arm_html.adb so it outputs more
anchors in appropriate places doesn't feel like "too much" to me.

I suppose it might slow down the page load time; would that actually be
significant?

Or it might slow down going to an anchor (a browser might do a linear
search); would that be noticable?

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Oliver Kleinke" <oliver.kleinke@c-01a.de> wrote in message 
news:20120511040710.52bbc3fd@vostro...
> Am Thu, 10 May 2012 11:11:25 +0100
> schrieb Stephen Leake <stephen_leake@stephe-leake.org>:
>
>> > A major problem of the formatter/RM sources is that they only
>> > provide partial semantic information about the contents, that IS
>> > 1995-style.
>>
>> What, exactly, is missing? Can you give an example?
>
> I'll provide one example:
>
> when ARM_Output.Small =>
>   if Indent = 0 then
>      return "Small";
>   elsif Indent = 1 then
>      return "Notes";
>   elsif Indent = 2 then
>      return "Annotations";
>
> As you can easily see the two style attributes 'Small' (paragraph/header
> style) and Indent (paragraph indentation) are used to determine the
> semantics of the paragraph's contents. So if you are a bright guy,
> you'll figure out what's bad about it.

I think you're confused. The ARM_Output packages only include formatting 
information (no semantics of any kind). Any semantics in those is an 
artifact of earlier versions (where all of the styles were named for their 
primary semantic use). For instance, in the above, all you are looking at is 
the names of the styles, which don't necessarily reflect in any way their 
semantic content - it's just a mnemomic device to make it easy to see if the 
right styles are applied.

You could rename these "Foobar1", "Foobar2", and "Foobar3" without making 
any difference in the output.

An earlier version of the formatter had a batch of completely ad-hoc styles, 
some including names like the above. (But even then, there was no intent 
that there was any semantic information involved.) When I pulled the indent 
out into a separate parameter (something I did relatively recently), I used 
some cases like the above so the underlying style names didn't need to 
change (I didn't relish trying to redo the mapping in the RTF, the HTML is 
much easier to change).

There's plenty of semantic information in the original markup, but 
approximately 0% makes it to any implementation of Arm_Output. If you want 
to preserve that, you probably will have to do the conversion at a higher 
level than Arm_Form does.

                                    Randy.

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Oliver Kleinke <oliver.kleinke@c-01a.de> writes:

> Am Thu, 10 May 2012 11:11:25 +0100
> schrieb Stephen Leake <stephen_leake@stephe-leake.org>:
>
>> > A major problem of the formatter/RM sources is that they only
>> > provide partial semantic information about the contents, that IS
>> > 1995-style.
>> 
>> What, exactly, is missing? Can you give an example?
>
> I'll provide one example:
>
> when ARM_Output.Small =>
>    if Indent = 0 then
>       return "Small";
>    elsif Indent = 1 then
>       return "Notes";
>    elsif Indent = 2 then
>       return "Annotations";
>
> As you can easily see the two style attributes 'Small' (paragraph/header
> style) and Indent (paragraph indentation) are used to determine the
> semantics of the paragraph's contents. So if you are a bright guy,
> you'll figure out what's bad about it.
>
> More semantic markup would also facilitate the extraction of information
> from the RM, e.g. to feed the data into an IDE (Manuel Collado pointed
> that out).

This appears to be a snippet from arm_html.adb, in the function
Paragraph_Name (that's the only occurance of 'return "Small"'). It is
deducing a name for a style, presumably to enable the use of a CSS
style.

It might make sense to use semantic information directly to get the
style name, but the arm_form code takes an indirect approach. It already
has a notion of "Style", which is more fine-grained than the CSS style
names Randy chose to implement.

So this is an internal design choice in the HTML formatter, not a
feature of the Scheme source.


For example, here's a portion of the Syntax section of 3.6 Array Types,
from file 03B.MSS:

@begin{Syntax}
@Syn{lhs=<array_type_definition>,rhs="
   @Syn2{unconstrained_array_definition} | @Syn2{constrained_array_definition}"}


@Syn{lhs=<unconstrained_array_definition>,rhs="
   @key{array}(@Syn2{index_subtype_definition} {, @Syn2{index_subtype_definition}}) @key{of} @Syn2{component_definition}"}

@Syn{lhs=<index_subtype_definition>,rhs="@Syn2{subtype_mark} @key{range} <>"}

@Syn{lhs=<constrained_array_definition>,rhs="
   @key{array} (@Syn2{discrete_subtype_definition} {, @Syn2{discrete_subtype_definition}}) @key{of} @Syn2{component_definition}"}

@Syn{lhs=<discrete_subtype_definition>,rhs="@SynI{discrete_}@Syn2{subtype_indication} | @Syn2{range}"}

@ChgRef{Version=[2],Kind=[Revised],ARef=[AI95-00230-01],ARef=[AI95-00406-01]}
@Syn{lhs=<component_definition>,rhs="@Chg{Version=[2],New=<
   >,Old=<>}[@key{aliased}] @Syn2{subtype_indication}@Chg{Version=[2],New=<
 | [@key{aliased}] @Syn2{access_definition}>,Old=<>}"}
@end{Syntax}

That looks like the necessary semantic info is there.

And here's the "Notes" and "Examples" sections of that Scheme source:

@begin{Notes}
All components of an array have the same subtype. In particular, for an array
of components that are one-dimensional arrays, this means that all components
have the same bounds and hence the same length.

Each elaboration of an @nt<array_type_definition> creates
a distinct array type. A consequence of this is that each
object whose @nt<object_declaration> contains an @nt<array_type_definition>
is of its own unique type.
@end{Notes}

@begin{Examples}
@Leading@keepnext@i(Examples of type declarations with unconstrained array definitions: )
@begin(Example)
@key(type) Vector     @key(is) @key(array)(Integer  @key(range) <>) @key(of) Real;
@key(type) Matrix     @key(is) @key(array)(Integer  @key(range) <>, Integer @key(range) <>) @key(of) Real;
@key(type) Bit_Vector @key(is) @key(array)(Integer  @key(range) <>) @key(of) Boolean;
@key(type) Roman      @key(is) @key(array)(Positive @key(range) <>) @key(of) Roman_Digit; --@RI[ see @RefSecNum(Character Types)]
@end(Example)

The next paragraph shows an example of direct formatting in addition to
semantic markup:

@begin{WideAbove}
@leading@keepnext@i(Examples of type declarations with constrained array definitions: )
@end{WideAbove}
@begin(Example)
@key(type) Table    @key(is) @key(array)(1 .. 10) @key(of) Integer;
@key(type) Schedule @key(is) @key(array)(Day) @key(of) Boolean;
@key(type) Line     @key(is) @key(array)(1 .. Max_Line_Size) @key(of) Character;
@end(Example)

As with all markup, it's tempting to not make macros for _everything_,
but to do ad hoc formatting occasionally.

>> > Providing a modern HTML version does not exclude the possibility to
>> > provide a more 'compatible' version, 
>> 
>> You have yet to define what you mean by either "modern" or
>> "compatible", either by example or description.
>
> For instance the paragraphs have no anchors, thus the possibility of
> deep-linking is limited. The Index has neither anchors for the letters
> nor links to them at the top. 

Ok, there could easily be more anchors. That's easy to change in the
arm_form sources.

I don't see how that has anything to do with "modern"; the requirement
for lots of anchors is implicit in the notion of hypertext, which is
ancient!

I would say "more complete navigation" for this, rather than "more
modern". 

Nor does it require a radical new tool; just a minor addition to the
current tool.

> I can think of a lot more.

Please do, and post them here, or (better), post patches to arm_form
Ada code.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 04:07:10 +0200, Oliver Kleinke  
<oliver.kleinke@c-01a.de> a écrit:
> For instance the paragraphs have no anchors, thus the possibility of
> deep-linking is limited. The Index has neither anchors for the letters
> nor links to them at the top. I can think of a lot more.

You just get what you wished.

Here is a quote from a mail from the Ada‑Comment list, as just received  
today:

> There is a new draft of the proposed Ada 2012 standard available at
> http://www.ada-auth.org/standards/ada12.html. This draft corrects a few
> minor issues that have been reported along with a number of line break  
> and
> indentation problems. The minor issues are all collected in AI05-0298-1
> (http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ai05s/ai05-0298-1.txt).
>  In addition, the HTML versions have a new feature, suggested on
> comp.lang.ada: there now are anchors for each paragraph. That means that  
> it
> is possible to write a link for any paragraph in the standard. Just put
> "#p<num>" after the link for the clause, where <num> is the paragraph  
> number
> minus any version number ("/2"). [We can't include the version numbers  
> as a
> slash is not allowed in anchor names, and changing it to some other
> character is not any easier than dropping it.]
>  For instance, to link to paragraph 13.11.4(13/3), use
> http://www.ada-auth.org/standards/12rm/html/RM-13-11-4.html#p13
> For an inserted paragraph, the period and following is included, but not  
> the
> slash. Linking to A.18.9(73.1/3) would require writing
> http://www.ada-auth.org/standards/12rm/html/RM-A-18-9.html#p73.1
>                        Randy Brukardt, ARG Editor.
>

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Oliver Kleinke <oliver.kleinke@c-01a.de> writes:
>
>> Also, the way the Formatter sources are provided sucks major --
>> cvsweb, you have to click around a lot until you have a complete set
>> of files plus some of the HEAD versions have been broken.
>
> Yes, but that's why I provide a .tar.gz of the full source: 
>
> http://www.stephe-leake.org/ada/arm_info-20120428-src.tar.gz
>
> http://www.stephe-leake.org/ada/arm.html

In addition, the Makefile in that package automates the task of pulling
current sources from Randy's CVS head. I've never had any trouble with it.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Jerrid Kimball <jerrid@kimball.co> writes:

> Thank you very much!  These are very nice and emacs seems to handle
> info pages very well.

Good to get some feedback :)

> I'm slowly getting to putting some modern-looking versions on the web
> based on the work of a fellow #ada IRC channel visitor.  I hope to get
> to it soon.  I'll keep CLA informed!

Hmm. What is "not modern" about info in Emacs? Many people think it is
the best of the currently available IDEs.

I think you need a more precise adjective :)

But if you do come up with something useful, perhaps it could be
incorporated into the ada-reference-manual Debian package.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Jerrid Kimball]

On 05/01/2012 06:51 AM, Stephen Leake wrote:
> Jerrid Kimball<jerrid@kimball.co>  writes:
>
>> Thank you very much!  These are very nice and emacs seems to handle
>> info pages very well.
>
> Good to get some feedback :)
>
>> I'm slowly getting to putting some modern-looking versions on the web
>> based on the work of a fellow #ada IRC channel visitor.  I hope to get
>> to it soon.  I'll keep CLA informed!
>
> Hmm. What is "not modern" about info in Emacs? Many people think it is
> the best of the currently available IDEs.

You've encountered lexical ambiguity.  I didn't intend to suggest that 
emacs' display of the info page isn't modern.  My intent is to 
eventually put a RM tool on the interwebs that eclipses the official RM 
in its presentation and accompanying functionality.  It's just another 
thing that will make Ada more appealing to the uninitiated.  Small steps..

>
> I think you need a more precise adjective :)
>
> But if you do come up with something useful, perhaps it could be
> incorporated into the ada-reference-manual Debian package.
>

Jerrid

Re: Ada Reference Manual 2012 in info format

[Manuel Collado]

El 03/05/2012 17:03, Jerrid Kimball escribi�:
> On 05/01/2012 06:51 AM, Stephen Leake wrote:
>> Jerrid Kimball<jerrid@kimball.co> writes:
>>
>>> Thank you very much! These are very nice and emacs seems to handle
>>> info pages very well.
>>
>> Good to get some feedback :)
>>
>>> I'm slowly getting to putting some modern-looking versions on the web
>>> based on the work of a fellow #ada IRC channel visitor. I hope to get
>>> to it soon. I'll keep CLA informed!
>>
>> Hmm. What is "not modern" about info in Emacs? Many people think it is
>> the best of the currently available IDEs.
>
> You've encountered lexical ambiguity. I didn't intend to suggest that
> emacs' display of the info page isn't modern. My intent is to eventually
> put a RM tool on the interwebs that eclipses the official RM in its
> presentation and accompanying functionality. It's just another thing
> that will make Ada more appealing to the uninitiated. Small steps..
>
>>
>> I think you need a more precise adjective :)
>>
>> But if you do come up with something useful, perhaps it could be
>> incorporated into the ada-reference-manual Debian package.

If the aim is to make the ARM usable as a reference for developers (say 
from an IDE), then it will be necessary to have it indexed also by:
- language keywords
- library functions and other global symbols

In its current form, the ARM index is not adequate for using it as 
context sensitive help from within an Ada IDE.

To be more precise, you can't put the cursor in an editing window over 
an Ada keyword or over a library item identifier, request help on it, 
and automagically have the ARM opened at an appropriate place (or be 
offered a choice among appropriate places, if there are several).

Compare this with the Ada Programming WikiBook, that have a dedicated 
page for each individual Ada language keyword.

-- 
Manuel Collado - http://lml.ls.fi.upm.es/~mcollado

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Manuel Collado" <m.collado@domain.invalid> wrote in message 
news:jnuurq$in0$1@speranza.aioe.org...
...
> If the aim is to make the ARM usable as a reference for developers (say 
> from an IDE), then it will be necessary to have it indexed also by:
> - language keywords
> - library functions and other global symbols

It is, of course, indexed by those in Annexes P and Q, but...

> In its current form, the ARM index is not adequate for using it as context 
> sensitive help from within an Ada IDE.

...this is certainly true; the indexes were not created with that in mind. 
But note that all of those (text) indexes are created by a program and it 
would be easy enough for someone to write a machine-readable index as 
well -- it's all just Ada code, after all.

                                            Randy.

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Jerrid Kimball <jerrid@kimball.co> writes:

> On 05/01/2012 06:51 AM, Stephen Leake wrote:
>> Jerrid Kimball<jerrid@kimball.co>  writes:
>>
>>> Thank you very much!  These are very nice and emacs seems to handle
>>> info pages very well.
>>
>> Good to get some feedback :)
>>
>>> I'm slowly getting to putting some modern-looking versions on the web
>>> based on the work of a fellow #ada IRC channel visitor.  I hope to get
>>> to it soon.  I'll keep CLA informed!
>>
>> Hmm. What is "not modern" about info in Emacs? Many people think it is
>> the best of the currently available IDEs.
>
> You've encountered lexical ambiguity.  

Yes, which is why I asked for clarification.

> I didn't intend to suggest that emacs' display of the info page isn't
> modern. 

Ok, good.

> My intent is to eventually put a RM tool on the interwebs that
> eclipses the official RM in its presentation and accompanying
> functionality. 

In what way? Can you point to an example of what you intend to do?

Intending to "eclipse" an existing valuable resource doesn't sound very
friendly, just competitive.

> It's just another thing that will make Ada more appealing to the
> uninitiated. 

"More appealing" is more friendly. But that needs to start with a survey
of the uninitiated; not an easy thing to do.

> Small steps..

Reformatting the entire ARM is _not_ a small effort!

Perhaps you could spend that energy improving the Ada Programming
wikibook, instead?

>> But if you do come up with something useful, perhaps it could be
>> incorporated into the ada-reference-manual Debian package.

Or the upstream source code.

In particular, code to process the Scheme source and output a GPS- or
Eclipse- friendly format for the index would be very nice.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Fri, 04 May 2012 09:58:34 +0200, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:
>> Small steps..
>
> Reformatting the entire ARM is _not_ a small effort!
>
> Perhaps you could spend that energy improving the Ada Programming
> wikibook, instead?

I feel some low level reformatting may be as much worth as a contribution  
to the Ada wikibook: a DITA formated ARM may be the best option among all.  
As the numerous DITA publishing chains support many target formats (my  
favorite is the webhelp format, provided by Ditac from XMLMind), no one  
would bother any more about what the actual format is. That's the benefit  
of single sourcing, as they like to say in the DITA world.

But they may be reasons we don't know for the source format to be what it  
actually is.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

"Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr> writes:

> Le Fri, 04 May 2012 09:58:34 +0200, Stephen Leake
> <stephen_leake@stephe-leake.org> a écrit:
>>> Small steps..
>>
>> Reformatting the entire ARM is _not_ a small effort!
>>
>> Perhaps you could spend that energy improving the Ada Programming
>> wikibook, instead?
>
> I feel some low level reformatting may be as much worth as a
> contribution to the Ada wikibook: a DITA formated ARM may be the best
> option among all.  

(I assume you mean this:
http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture)

It should be possible to write some Ada code so arm_form can transform
the Scheme to DITA, just as it now outputs texinfo format.

That does seem to be worth doing. Perhaps it would even be a good route
to PDF with hyperlinks!

I don't remember how long it took me to get texinfo output working; a
couple of months of occasional effort, I think.

DITA looks more complex, but if you understand the format, it should be
a similar effort.

> But they may be reasons we don't know for the source format to be what
> it actually is.

That's easy; apparently DITA was invented in 2001; the ARM scheme
sources were started for Ada 95 (if not earlier).

Also, Randy's Scheme format specifically supports multiple versions,
with change tracking, in one source. I've only skimmed the DITA table of
contents at
http://docs.oasis-open.org/dita/v1.1/CS01/archspec/archspec.html; you
might be able to do that in DITA source, but it's not obvious.

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Sun, 06 May 2012 18:13:26 +0200, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:
> (I assume you mean this:
> http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture)

Yah :)

> That does seem to be worth doing. Perhaps it would even be a good route
> to PDF with hyperlinks!

If you say that's worth (I wanted to know), I will have a real look at  
this task, during the year.

>> But they may be reasons we don't know for the source format to be what
>> it actually is.
>
> That's easy; apparently DITA was invented in 2001; the ARM scheme
> sources were started for Ada 95 (if not earlier).

Oops, you're right, indeed.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1062 bytes --]

"Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message 
news:82havtjnix.fsf@stephe-leake.org...
> "Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> writes:
...
>> But they may be reasons we don't know for the source format to be what
>> it actually is.
>
> That's easy; apparently DITA was invented in 2001; the ARM scheme
> sources were started for Ada 95 (if not earlier).

Right. The Ada 95 sources used the same tool as the Ada 83 sources, with a 
new set of macros.

I just wrote an Ada program to process the existing Ada 95 source code (with 
a few simplifications; mainly, I got rid of all of the macros and the 
support for that). That meant we were no longer dependent on an ancient (but 
powerful) text formatter; anyone with an Ada compiler can build a version of 
my formatter.

It's fairly easy to add a new output module (as Stephen can attest); that's 
the preferred way to make new versions of the Standard, simply because it 
will handle both older and newer editions of the Standard.

                            Randy.

Re: Ada Reference Manual 2012 in info format

[Yannick Duchêne (Hibou57)]

Le Sun, 29 Apr 2012 17:22:48 +0200, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:

> I've posted the Ada Reference Manual 2012 in info format on my web page:
>
> http://www.stephe-leake.org/ada/arm.html
>
> This is draft 17 of ARM 2012, not yet formally approved by ISO.

Can you remind the planned date? I forget it.

-- 
“Syntactic sugar causes cancer of the semi-colons.” [1]
“Structured Programming supports the law of the excluded muddle.” [1]
[1]: Epigrams on Programming — Alan J. — P. Yale University

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 739 bytes --]

"Yannick Duch�ne (Hibou57)" <yannick_duchene@yahoo.fr> wrote in message 
news:op.wdqo8lovule2fv@douda-yannick...
>Le Sun, 29 Apr 2012 17:22:48 +0200, Stephen Leake 
><stephen_leake@stephe-leake.org> a �crit:
>
>> I've posted the Ada Reference Manual 2012 in info format on my web page:
>>
>> http://www.stephe-leake.org/ada/arm.html
>>
>> This is draft 17 of ARM 2012, not yet formally approved by ISO.
>
>Can you remind the planned date? I forget it.

This is ISO we're talking about, things happen on their schedule, not ours. 
We *hope* that all of that will be finished by the end of the year, but 
there is no certainty in these things. When it's formally approved, it will 
be announced.

                             Randy.

Re: Ada Reference Manual 2012 in info format

[Oliver Kellogg]

Thanks for making this available, it just came to the rescue for me as I didn't have an Ada2012 RM handy and http://www.ada-auth.org is currently down.
-- Oliver

On Sunday, April 29, 2012 5:22:48 PM UTC+2, Stephen Leake wrote:
> I've posted the Ada Reference Manual 2012 in info format on my web page:
> 
> 
> 
> http://www.stephe-leake.org/ada/arm.html
> 
> 
> 
> This is draft 17 of ARM 2012, not yet formally approved by ISO. But
> 
> according to http://www.ada-auth.org/standards/ada12.html, there will
> 
> only be minor editorial changes, so this should be useful.
> 
> 
> 
> That file also includes the 2005 info files, with some bugs fixed in the
> 
> info format from my previous release. Useful for people stuck with
> 
> antiquated compilers :).
> 
> 
> 
> There's also a Debian package containing this waiting to be uploaded. If
> 
> you've ever felt the urge to get involved in Debian, now is the time! 
> 
> (I'm dropping out of Debian; I don't have time or energy anymore).
> 
> 
> 
> -- 
> 
> -- Stephe

Re: Ada Reference Manual 2012 in info format

[Stephen Leake]

Oliver Kellogg <okellogg@users.sourceforge.net> writes:

> Thanks for making this available, it just came to the rescue for me as
> I didn't have an Ada2012 RM handy and http://www.ada-auth.org is
> currently down.

You're welcome; it is nice to hear feedback.

The info version of the final 2012 manual is available now, at the same URL:

http://www.stephe-leake.org/ada/arm.html

-- 
-- Stephe

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message 
news:85liadjzv7.fsf@stephe-leake.org...
> Oliver Kellogg <okellogg@users.sourceforge.net> writes:
>
>> Thanks for making this available, it just came to the rescue for me as
>> I didn't have an Ada2012 RM handy and http://www.ada-auth.org is
>> currently down.
>
> You're welcome; it is nice to hear feedback.
>
> The info version of the final 2012 manual is available now, at the same 
> URL:
>
> http://www.stephe-leake.org/ada/arm.html

I finally added that to the "official" Ada 2012 page last week (just in time 
for the server to break on Saturday morning). So interested users don't have 
to be members here to find out about it's existence.

                               Randy.

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 2/25/2013 5:27 PM, Randy Brukardt wrote:
> "Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message

>>
>> http://www.stephe-leake.org/ada/arm.html
>
> I finally added that to the "official" Ada 2012 page last week (just in time
> for the server to break on Saturday morning). So interested users don't have
> to be members here to find out about it's existence.
>
>                                 Randy.
>

Something I always wondered about. Why do the Ada standards
have copy right on them by specific companies? How does
this relate to Ada being open/ISO/ANSI etc... standard?

I am just little confused on what is being copy righted here
that is all.

For example, Ada 2012 on the above page says:

-----------------
  Copyright � 1992, 1993, 1994, 1995 Intermetrics, Inc.
Copyright � 2000 The MITRE Corporation, Inc.
Copyright � 2004, 2005, 2006 AXE Consultants
Copyright � 2004, 2005, 2006 Ada-Europe
Copyright � 2008, 2009, 2010, 2011, 2012 AXE Consultants
-----------------

Is this copyright just for the manual itself, or Ada
the "language" in some sense?

thanks
--Nasser

Re: Ada Reference Manual 2012 in info format

[Robert A Duff]

"Nasser M. Abbasi" <nma@12000.org> writes:

> Something I always wondered about. Why do the Ada standards
> have copy right on them by specific companies?

I don't know.  Intermetrics assigned their copyright to the U.S.
Government, but the others don't say that.  I've no idea what
that's all about.

>...How does
> this relate to Ada being open/ISO/ANSI etc... standard?

All of the copyright holders grant liberal permissions to
copy (read the part starting "This document may be copied...").
That makes it pretty "open".  You won't find that kind of
wording in (say) your favorite Robert Ludlum novel.

> Is this copyright just for the manual itself, or Ada
> the "language" in some sense?

I'm not a lawyer, but I think copyrights apply to documents,
not to languages or whatever else might be described by the
documents.

- Bob

Re: Ada Reference Manual 2012 in info format

[Nasser M. Abbasi]

On 2/26/2013 7:23 AM, Robert A Duff wrote:

> I'm not a lawyer, but I think copyrights apply to documents,
> not to languages or whatever else might be described by the
> documents.
>

Thanks. I think this sounds right and sort of what I thought
but wanted to make sure.

So to give an example, it is like someone writing a book
to describe and explain Newton's laws of physics. The author
will copy-right the book itself, but Newton's laws themselves
which are described in the book are still "open" and can be
used by anyone else without getting  permission from the
book author to use them.

In this case, the laws happened to be the Ada language rules
and the authors are these companies listed. But the Ada
rules themselves are open and can be used by anyone
without permission.

--Nasser

Re: Ada Reference Manual 2012 in info format

[Randy Brukardt]

"Robert A Duff" <bobduff@shell01.TheWorld.com> wrote in message 
news:wcchakzryys.fsf@shell01.TheWorld.com...
> "Nasser M. Abbasi" <nma@12000.org> writes:
...
>>...How does
>> this relate to Ada being open/ISO/ANSI etc... standard?
>
> All of the copyright holders grant liberal permissions to
> copy (read the part starting "This document may be copied...").
> That makes it pretty "open".  You won't find that kind of
> wording in (say) your favorite Robert Ludlum novel.

Right. And more importantly, if we had just given the copyrights to ISO 
(which is the normal procedure), then the Standard would not be "open" in 
any practical sense: you'd have to pay ISO in order to distribute it (with 
some exceptions that have been created in recent years). As such, we've been 
keeping the ISO and original versions of the Standard separate, and 
maintaining the original "anyone may copy" wording.

My understanding was that this was vetted by MITRE's lawyers back in the 
Corrigendum days (that's why the second set of wording is different than the 
first); I've maintained the same wording on more recent editions but we 
haven't rechecked if the "law" has changed significantly (I'm surely not a 
lawyer, either, other than for Ada :-).

                                                   Randy.

Re: Ada Reference Manual 2012 in info format

[M. Strobel]

Am 26.02.2013 00:27, schrieb Randy Brukardt:
> "Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message 
> news:85liadjzv7.fsf@stephe-leake.org...
>> Oliver Kellogg <okellogg@users.sourceforge.net> writes:
>>
>>> Thanks for making this available, it just came to the rescue for me as
>>> I didn't have an Ada2012 RM handy and http://www.ada-auth.org is
>>> currently down.
>>
>> You're welcome; it is nice to hear feedback.
>>
>> The info version of the final 2012 manual is available now, at the same 
>> URL:
>>
>> http://www.stephe-leake.org/ada/arm.html
> 
> I finally added that to the "official" Ada 2012 page last week (just in time 
> for the server to break on Saturday morning). So interested users don't have 
> to be members here to find out about it's existence.

hmmm there is no membership in a newsgroup... and google is happily copying it all
presenting it as it's own

/Str.