From AlphaWiki

Help: AIDESyntaxDiscussion

This page serves as a forum for discussing proposals for the Help.AIDE markup syntax. Currently, AIDE and AIDA refer to two different markup proposals for Alpha documentation.

The ADT is currently developing a system for maintaining all of Alpha's help files in a cvs, which can be accessed via Alpha so that any user can obtain help for any topic via the www.

Each file is referred to as an AIDE. AIDE stands for either ''Alpha Information, Documentation, and Enhancements or the Alpha Information Development Environment.'' Bernard suggested the name AIDA which translates Alpha Information and Documentation Archive. The final name of this system is still under discussion.

The AIDE system is based on TIP (for Tcl Improvement Proposals). TIPrender was originally developed by Donal Fellows and has been adapted by Daniel to render AIDE files -- the current name of this system is Help.AIDERender.

The Help.AIDERender syntax was based upon that used by the TIPrender. Bernard has proposed a different set of mark-up tags to be used, as well as a different method of presentation of all Help files to the user. This discussion has been taking place on the alphadocs list serv -- for more information (and links to the archives) see the AlphaTclMailingLists page.


AIDE->AIDA Transition (DonavanHall)


A compromise approach would be to include all of the present AIDE markup as a valid subset of AIDA. The double paren markup of AIDA is fine with me, but I'm no expert at creating useful tags (too many years of playing with Setext, I imagine). This suggestion comes in response to Craig's excellent observation that all of the source documents will need to be written in AIDA even if they are down converted into AIDE before plugging into AIDErender. What this means is that people who want the added sophistication can make use of the AIDA markup, but people who only need the basic AIDE markup can still write valid documents that way. Eventually, we can modify AIDErender into AIDArender.

Thus the documentation content markup I suggested should probably (if we all agree to this) become:

 
   ((@ menu-item )):
      Indicate a menu item.

   ((! keyboard-characters )): 
	Indicate keyboard input.

  ((< key-name )):
      Indicate the conventional name for a key on a keyboard.

   ((` text )):
      Indicate text that is a literal example of a sequence of characters.

   ((+ metasyntactic-variable )):
      Indicate a metasyntactic variable.

   ((% environment-variable )):
      Indicate an environment variable.

   ((" file-name )):
      Indicate the name of a file.

   ((# command )):
      Indicate the name of a command.

   ((- option )):
      Indicate a command-line option.

   ((& term )):
      Indicate the introductory or defining use of a term.

   ((^ reference )):
      Indicate the name of a book.

or should they be marked like ((@ menu-item @))??

Does this compromise sound acceptable?? The advantages of this are continued support for simple/basic markup that anybody can learn in a few minutes coupled with a set of more sophisticated tags for serious documentation writers. Handling of AIDA tags can be implemented in AIDErender slowly.


Craig's comments :

I like this compromise. Here's one way to interpret it:

The web-based version of the aiderender has a basic set of mark-up tags, which enables it to convert source .aide files to HTML, PDF, LaTeX etc. Alpha uses these tags to properly render a file.

Alpha also has an additional set of mark-up tags because it can handle things in a more sophisticated manner. This is actually the current situation -- everything in 'help::colourAlphaTags' (the proc formerly known as 'help::colourHeadingsEtc') is an extra mark-up tag that is generally ignored by the aiderender. What I hear Donavan proposing is that we enhance these tags by introducing a new '((x ' mark-up syntax that will be handled in a variety of ways, perhaps by triggering a filter. If we find it desirable we could also hide these tags using Bernard's white-out procs, but for now we should assume that Alphatk cannot handle this (and for the moment the aiderender certainly cannot).

Source files on the cvs will contain all tags, including all those that the aiderender doesn't recognize, so it is important that the tags not be intrusive or detract from either the visual layout or the readability of the AIDE. One goal is to teach the aiderender how to deal with these tags, but that can happen over time.


Shortened Aida notation (bd)


My initial proposal for a system of tags was more or less the following (some tags come in pairs) :

 
   ((babs eabs)) Beginning/end of abstract
   ((bdl   edl)) Beginning/end of description list
   ((bol   eol)) Beginning/end of ordered list
   ((bul   eul)) Beginning/end of unordered list
   ((it          Ordered/unordered lists item
   ((di          Description list term
   ((btbl etbl)) Beginning/end of table
   ((hli         Horizontal line (in table)
   ((row         Table's row
   ((toc         Insert a table of contents
   ((hr          Insert horizontal rule
   ((img         Insert an image
   ((|       |)) Beginning/end of verbatim
   (|            Each line in the verbatim environment
   ((sh          Section header
   ((ssh         Subsection header
   ((sssh        Subsubsection header
   (>         <) Index entry
   ((p           Paragraph

To make the notation shorter, I now propose the following modifications

 
   ((ab        instead of  ((babs
   ((dl        instead of  ((bdl
   ((ol        instead of  ((bol
   ((ul        instead of  ((bul
   ((hl        instead of  ((hli
   ((im        instead of  ((img
     ab))      instead of    eabs))
     dl))      instead of     edl))
     ol))      instead of     eol))
     ul))      instead of     eul))
   ((t         instead of  ((btbl
      t))      instead of    etbl))
   ((tr        instead of  ((row

To this could be added

 
   ((np        for a newpage
   ((q   q))   to make a quotation environment
   ((nd        to make a node (like @node in TexInfo)
   ((a    ))   to make anchors

Craig has suggested ((~ ((~~ instead of ((sh and ((ssh : my only objection is that on a french keyboard the tilda is nowhere : you must type option-n which produces nothing (dead key) and then press the space bar. Not everybody is used to that since there is no tilde in french. It is a frequently asked question here : how do you type a tilda ? sh is Groff's notation.

Concerning tables I now suggest in fact ((t0 and ((t1 to make tables respectively with or without a frame. I implemented this in aidamode and it works fine.


Short Tags (bd)


Here is the actual list of tags (may 23rd) with their meaning

Sections / Structure

 
   ((ab ab))    Beginning/end of abstract
   ((sh         Section header
   ((ssh        Subsection header
   ((sssh       Subsubsection header
   ((toc        Insert a table of contents
   ((np         New page
   ((p          Paragraph
   ((q  q))     Beginning/end of quotation
   ((hr         Insert horizontal rule

Lists

 
   ((dl dl))    Beginning/end of description list
   ((ol ol))    Beginning/end of ordered list
   ((ul ul))    Beginning/end of unordered list
   ((it         Ordered/unordered lists item
   ((di         Description list term

Tables

 
   ((t0 t))     Beginning/end of table (without border)
   ((t1 t))     Beginning/end of table (with border)
   ((tr         Table's row
   ((hl         Horizontal line (in table)

Text Markers, Images, Links, etc

 
   ((im  ))     Insert an image
   ((|  |))     Beginning/end of verbatim
   (|           Verbatim line
   (>   <)      Index entry  (? see Donavan's proposal)
   ((a  ))      Named anchor
   ((nd         Node

To this list should be added the above list proposed by Donavan for the indexing purpose. So I'm not sure the pair of tags I propose in this list (for index entries) is really necessary. We have to experiment to get a more precise idea of what is necessary.

I have been experimenting a lot with almost all these tags (except the image and anchor tags which deserve some reflection).

The ((nd tag is inspired by the @node command. As Donavan pointed out nodes are difficult to maintain.


Proposed Changes to the above (cbu, 05-23-01)


In principle I have no objection to the above, but I have some proposed changes partly for aesthetic reasons, to make some of the tags make visual sense with glyphs, or to put everything related to 'tables' (for example) in the 't' tag-space.

Sections / Structure

 
   ((/ /))      Beginning/end of abstract
   ((=          Section header
   ((==         Subsection header
   ((===        Subsubsection header
   ((toc        Insert a table of contents
   ((n          New page
   ((p          Paragraph
   ((>  <))     Beginning/end of quotation
   ((-          Insert horizontal rule

Lists

 
   ((ld ld))    Beginning/end of description list
   ((lo lo))    Beginning/end of ordered list
   ((lu lu))    Beginning/end of unordered list
   ((li         Ordered/unordered lists item
   ((lt         Description list term

Tables

 
   ((t0 t))     Beginning/end of table (without border)
   ((t1 t))     Beginning/end of table (with border)
   ((tr         Table's row
   ((t-         Horizontal line (in table)

Text Markers, Images, Links, etc

 
   ((im  ))     Insert an image
   ((|  |))     Beginning/end of verbatim
   (|           Verbatim line
   (('  '))     Text with emphasis (italics)
   ((a  ))      Named anchor
   ((nd         Node

                Index entry -- see Donavan's proposal above,
                but I would suggest that they come in the form of
                (>! <) rather than ((! just so that we can easily
                distinguish an index-marker from other tags.

Note that the current aiderender also makes use of

 
   [asdfasd]    for AIDE links
            to insert real ['s
   index        to insert AIDE indices

We probably need to consider these as well.


Minor Changes (bd)


I came back to ((np for a new page instead of ((n because ((n is a substring of ((nd (node tag).

The closing tag for images has been changed to im)) maybe only temporarily. I want to experiment with the possibility of specifying a caption text inside the image declaration. So it could look like :

((im url_of_the_image : caption_text im))

with a separating colon or alternatively :

((im url_of_the_image

caption_text im))

Section tags have become : ((s1, ((s2 and ((s3.

For quotation environments, back to : ((q q))

Retrieved from http://alphatcl.sourceforge.net/wiki/pmwiki.php/Help/AIDESyntaxDiscussion
Page last modified on March 26, 2008, at 01:56 PM