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

[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

[Randy Brukardt]

"Jerrid Kimball" <jer...@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.

[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 | tho...@12boo.net | http://12boo.net

[Yannick Duchêne (Hibou57)]

Le Tue, 01 May 2012 08:06:21 +0200, Thomas Løcke <tho...@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

[Stephen Leake]

Jerrid Kimball <jer...@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

[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

[Jerrid Kimball]

On 05/01/2012 06:51 AM, Stephen Leake wrote:
> Jerrid Kimball<jer...@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

[Jerrid Kimball]

On 04/30/2012 10:19 PM, Randy Brukardt wrote:
> "Jerrid Kimball"<jer...@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

[J Kimball]

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

[Yannick Duchêne (Hibou57)]

Le Thu, 03 May 2012 16:26:14 +0200, Jacob Sparre Andersen <spa...@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.

[Yannick Duchêne (Hibou57)]

Le Sun, 29 Apr 2012 17:22:48 +0200, Stephen Leake
<stephe...@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.

[Manuel Collado]

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

[Randy Brukardt]

"Yannick Duchêne (Hibou57)" <yannick...@yahoo.fr> wrote in message
news:op.wdqo2emfule2fv@douda-yannick...

Le Thu, 03 May 2012 16:26:14 +0200, Jacob Sparre Andersen <spa...@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.

[Randy Brukardt]

"Yannick Duchêne (Hibou57)" <yannick...@yahoo.fr> wrote in message

news:op.wdqo8lovule2fv@douda-yannick...

>Le Sun, 29 Apr 2012 17:22:48 +0200, Stephen Leake
><stephe...@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.

[Randy Brukardt]

"Manuel Collado" <m.co...@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.

[Randy Brukardt]

"Jerrid Kimball" <jer...@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.

[BrianG]

On 05/03/2012 07:25 PM, Randy Brukardt wrote:
> "Jerrid Kimball"<jer...@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

[Stephen Leake]

Jerrid Kimball <jer...@kimball.co> writes:

> On 05/01/2012 06:51 AM, Stephen Leake wrote:
>> Jerrid Kimball<jer...@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

[Yannick Duchêne (Hibou57)]

Le Fri, 04 May 2012 09:58:34 +0200, Stephen Leake
<stephe...@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.

[Stephen Leake]

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

> Le Fri, 04 May 2012 09:58:34 +0200, Stephen Leake
> <stephe...@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

[Yannick Duchêne (Hibou57)]

Le Sun, 06 May 2012 18:13:26 +0200, Stephen Leake
<stephe...@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.

[Randy Brukardt]

"Stephen Leake" <stephe...@stephe-leake.org> wrote in message
news:82havtj...@stephe-leake.org...

> "Yannick Duchêne (Hibou57)" <yannick...@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.

[Oliver Kleinke]

Am Thu, 3 May 2012 18:25:53 -0500
schrieb "Randy Brukardt" <ra...@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

[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

[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

[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.

[Dmitry A. Kazakov]

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?

[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.

[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>

[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"

[Jerrid Kimball]

> ....
>
> 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

[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.

[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.

[Simon Wright]

Jerrid is right.

[Yannick Duchêne (Hibou57)]

Le Wed, 09 May 2012 16:09:10 +0200, Dmitry A. Kazakov
<mai...@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.

[Randy Brukardt]

"Oliver Kleinke" <oliver....@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.

[Randy Brukardt]

"Jerrid Kimball" <jer...@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.

[Randy Brukardt]

"Oliver Kleinke" <oliver....@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.

[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
> <mai...@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.

[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.

[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

[Simon Wright]

"Nasser M. Abbasi" <n...@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).

[Stephen Leake]

Oliver Kleinke <oliver....@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

[Stephen Leake]

Georg Bauhaus <rm.dash...@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

[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!"

[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

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 09:13:56 +0200, Dmitry A. Kazakov
<mai...@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?

[Yannick Duchêne (Hibou57)]

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

> "Jerrid Kimball" <jer...@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.

[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
> <mai...@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.

[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

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 17:02:30 +0200, Dmitry A. Kazakov
<mai...@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.

[Yannick Duchêne (Hibou57)]

Le Thu, 10 May 2012 17:05:33 +0200, Manuel Collado
<m.co...@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).

[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
> <mai...@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?

[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.co...@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).

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 00:15:19 +0200, Manuel Collado
<m.co...@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.

[Oliver Kleinke]

Am Thu, 10 May 2012 11:11:25 +0100
schrieb Stephen Leake <stephe...@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?

[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/

[Oliver Kleinke]

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

> "Oliver Kleinke" <oliver....@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

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 04:07:10 +0200, Oliver Kleinke
<oliver....@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.

[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

[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"

[Martin]

+1 - great idea

[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.co...@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?

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 12:47:44 +0200, Manuel Collado

<m.co...@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.co...@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.

[Stephen Leake]

"Nasser M. Abbasi" <n...@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

[Stephen Leake]

"Nasser M. Abbasi" <n...@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

[Stephen Leake]

"Yannick Duchêne (Hibou57)" <yannick...@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

[Stephen Leake]

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

> Oliver Kleinke <oliver....@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

[Yannick Duchêne (Hibou57)]

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

> "Yannick Duchêne (Hibou57)" <yannick...@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).

[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.

[Simon Wright]

Stephen Leake <stephe...@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".

[Nasser M. Abbasi]

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

[Simon Wright]

Jacob Sparre Andersen <spa...@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!!).

[Simon Wright]

Simon Wright <si...@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 ...

[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

[Ludovic Brenta]

Iceweasel here is happy too :)

--
Ludovic Brenta.

[Simon Wright]

Simon Wright <si...@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;

[Randy Brukardt]

"Randy Brukardt" <ra...@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
(ag...@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.

[Randy Brukardt]

"Manuel Collado" <m.co...@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.

[Randy Brukardt]

"Stephen Leake" <stephe...@stephe-leake.org> wrote in message
news:82d36bg...@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.

[Randy Brukardt]

"Oliver Kleinke" <oliver....@c-01a.de> wrote in message

news:20120511043604.344c13a8@vostro...

> Am Wed, 9 May 2012 20:54:32 -0500
> schrieb "Randy Brukardt" <ra...@rrsoftware.com>:
>
>> "Oliver Kleinke" <oliver....@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.

[Randy Brukardt]

"Oliver Kleinke" <oliver....@c-01a.de> wrote in message

news:20120511040710.52bbc3fd@vostro...
> Am Thu, 10 May 2012 11:11:25 +0100
> schrieb Stephen Leake <stephe...@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.

[Stephen Leake]

Manuel Collado <m.co...@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

[Stephen Leake]

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

> Am Thu, 10 May 2012 11:11:25 +0100
> schrieb Stephen Leake <stephe...@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

[Stephen Leake]

"Yannick Duchêne (Hibou57)" <yannick...@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

[Stephen Leake]

> Simon Wright <si...@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

[Stephen Leake]

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

--
-- Stephe

[Simon Wright]

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

>> Simon Wright <si...@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.

[Manuel Collado]

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

[Manuel Collado]

El 12/05/2012 12:04, Stephen Leake escribió:
> Manuel Collado<m.co...@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]

El 11/05/2012 17:32, Simon Wright escribió:
> Jacob Sparre Andersen<spa...@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.

[Simon Wright]

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!

[Randy Brukardt]

"Manuel Collado" <m.co...@domain.invalid> wrote in message

news:joqqmr$ki4$1...@speranza.aioe.org...

> El 11/05/2012 17:32, Simon Wright escribió:
>> Jacob Sparre Andersen<spa...@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.

[Georg Bauhaus]

On 15.05.12 09:02, Randy Brukardt wrote:
> "Manuel Collado"<m.co...@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

[Yannick Duchêne (Hibou57)]

Le Fri, 11 May 2012 04:07:10 +0200, Oliver Kleinke
<oliver....@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

[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

[Stephen Leake]

Oliver Kellogg <okel...@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

[Randy Brukardt]

"Stephen Leake" <stephe...@stephe-leake.org> wrote in message

news:85liadj...@stephe-leake.org...

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.

[Nasser M. Abbasi]

On 2/25/2013 5:27 PM, Randy Brukardt wrote:
> "Stephen Leake" <stephe...@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