Re: Ada Reference Manual 2012 in info format

[Stephen Leake <stephen_leake@stephe-leake.org>]

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

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

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

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

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


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

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


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

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

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

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

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

That looks like the necessary semantic info is there.

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

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

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

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

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

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

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

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

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

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

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

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

> I can think of a lot more.

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

-- 
-- Stephe