From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,6487f59679c615d8 X-Google-NewGroupId: yes X-Google-Attributes: gida07f3367d7,domainid0,public,usenet X-Google-Language: ENGLISH,ASCII-7-bit Received: by 10.204.132.81 with SMTP id a17mr145517bkt.4.1336818769056; Sat, 12 May 2012 03:32:49 -0700 (PDT) Path: h15ni8621bkw.0!nntp.google.com!news2.google.com!npeer02.iad.highwinds-media.com!news.highwinds-media.com!feed-me.highwinds-media.com!post02.iad.highwinds-media.com!news.flashnewsgroups.com-b7.4zTQh5tI3A!not-for-mail From: Stephen Leake Newsgroups: comp.lang.ada Subject: Re: Ada Reference Manual 2012 in info format References: <82aa1ud0l3.fsf@stephe-leake.org> <20120509131736.63c924c8@vostro> <82lil0gxbm.fsf@stephe-leake.org> <20120511040710.52bbc3fd@vostro> Date: Sat, 12 May 2012 06:33:52 -0400 Message-ID: <82txzlu1rj.fsf@stephe-leake.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (windows-nt) Cancel-Lock: sha1:UE9K+5e0MmQilcAwTrP0h3v7wDk= MIME-Version: 1.0 X-Complaints-To: abuse@flashnewsgroups.com Organization: FlashNewsgroups.com X-Trace: cc1ab4fae3c50e029e66125163 X-Received-Bytes: 6270 Content-Type: text/plain; charset=us-ascii Date: 2012-05-12T06:33:52-04:00 List-Id: Oliver Kleinke writes: > Am Thu, 10 May 2012 11:11:25 +0100 > schrieb Stephen Leake : > >> > 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=,rhs=" @Syn2{unconstrained_array_definition} | @Syn2{constrained_array_definition}"} @Syn{lhs=,rhs=" @key{array}(@Syn2{index_subtype_definition} {, @Syn2{index_subtype_definition}}) @key{of} @Syn2{component_definition}"} @Syn{lhs=,rhs="@Syn2{subtype_mark} @key{range} <>"} @Syn{lhs=,rhs=" @key{array} (@Syn2{discrete_subtype_definition} {, @Syn2{discrete_subtype_definition}}) @key{of} @Syn2{component_definition}"} @Syn{lhs=,rhs="@SynI{discrete_}@Syn2{subtype_indication} | @Syn2{range}"} @ChgRef{Version=[2],Kind=[Revised],ARef=[AI95-00230-01],ARef=[AI95-00406-01]} @Syn{lhs=,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 creates a distinct array type. A consequence of this is that each object whose @nt contains an @nt 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