Re: Examples in Docs, was Re: Escape Sequences in Strings

[randhol+abuse@pvv.org (Preben Randhol)]

On Sat, 20 Jan 2001 15:00:46 GMT, Robert Dewar wrote:
>Yes, that seems like a good compromise but in this case I
>favor minimal markup, so that the documentation can still
>be easily read with ordinary editing tools while working
>with the source. One can imagine a universal environment
>allowing fancy markup, and that would be fine, if and
>when it is universal :-)

One could of course in the spirit of Ada, choose a markup system that
increases the readability without inflicting a lot of tag insertions :-)

GtkAda uses a system that looks something like this:

--  <description>
--  This widget implements a top level window.
--  It is used as the base class for dialogs, ...

[I have clipped off some of the text]

--  A window can also be modal, i.e. grab all the mouse and keyboard
--  events in the application while it is displayed.
--
--  </description>
--  <c_version>1.2.6</c_version>

[...]

   procedure Gtk_New
     (Window   : out Gtk_Window;
      The_Type : in  Gtk.Enums.Gtk_Window_Type := Gtk.Enums.Window_Toplevel);
   --  Create a new window.
   --  The_Type specifies the type of the window, and can be either a
   --  top level window, a dialog or a popup window. You will most often only
   --  need to use Window_Toplevel, the other types are mostly used internally
   --  by gtk+.
   --  A Popup window is used to display a temporary information window. It has
   --  no borders nor resizing handles.

To see how it looks on the web look at:

   http://gtkada.eu.org/docs/gtkada_rm_113.html#SEC475

This could be used to make reference manuals, not tutorials nor
spec documents, but think that that should be in a separate document.

-- 
Preben Randhol ---------------- http://www.pvv.org/~randhol/ --
iMy favorite editor is Emacs!<ESC>bcwVim<ESC>
                                         -- vim best-editor.txt