
[[title
  Tom Lord's (temporary) GNU Arch Page
]]


  Yes, it's the dreaded */under construction/* page.  If
  you're here to find some information about GNU Arch that is
  customarily found on this page, here are some links to popular
  pages.  Below that, a brief note about what's going on behind this
  site (why it's under construction and what it will be like shortly).

  //\Note:\// Most of these links take you to mirrors of the old
  site that used to be here.

  [[cartouche

    /The old top-level page -- / if you are looking for an old link
    not listed below, try looking
    here. <http://regexps.srparish.net/www>

    /"What is Revision Control" -- / a neutral description of what
    revision control is (not Arch specific although, obviously,
    reflective of the perspective of Arch's designer).
    <http://regexps.srparish.net/www/revctl-intro.html>

    /"An Overview of GNU Arch" -- / a brief list of (some of) the
    features that most distinguish Gnu Arch from competing systems.
    <http://regexps.srparish.net/www/arch-overview.html>

    /"How Arch Works" -- / a high level description of exactly what
    arch is and does.  If you're like me, the necessary vagueness of
    an "overview" like the previous link can be tantalizing but
    frustrating.  This short paper tries to give programmers and other
    technical types a slightly deeper picture.
    <http://regexps.srparish.net/www/arch-tech.html>

    /"A Tutorial Introduction to The arch Revision Control System" --
    / <http://regexps.srparish.net/www/tutorial/html/arch.html>

    /The user community wiki -- / not something I help to maintain at
    all but (or therefore :-) a popular alternative to the tutorial.
    Also a forum where people work on new ideas and designs for
    improvements to arch.  <http://wiki.gnuarch.org>
  ]]


* So.... what's up with *this* site, then?

 This site is turning into a /programmer's blog/: an organization and
 communiation tool for arch-using programmers.     The site will be
 the initial prototype and demonstration of /`gtla'/: a front-end 
 for /`GNU Arch'/ --- /`gtla'/ will be generating a lot of of the
 automated content for the blog itself.

 You can read about some of the motivation for the blog and for `gtla'
 generally in <"the previous edition of this home page" --
 ./index-prev.html>


* Well, Tom, Any Progress?

 You betcha.

 To build the programmer's blog, or for that matter many other kind of
 new UI for arch, I'll need to glue lots of components together.  In
 particular, the functionality of arch commands and scripts that serve
 as "report generators" has to, somehow, be translated for the UI
 being built.   In this case, there's a need to translate arch-related
 reports into HTML -- for inclusion in a blog.

 It's a shame to waste work, right?   If someone will go to the
 trouble of making a pleasingly and unambiguously formatted text
 display of a report -- is there some reason that that work can't 
 directly translate into other kinds of display (such as HTML or GUI)?

 I think a wiki language is ideal for the interface between low-level
 report generation tools and higher-level user interface presentation
 layers.   There are several reasons for this:

 /Wiki syntax is attractive -- / The low-level report generators 
 can produce human-readable, even attractive (plain-text) output.

 /Wiki syntax can be precise -- / Wiki syntax for structured data
 from report generators can be completely unambiguous and easy to
 machine parse.

 /Wiki presentation is naturally flexible and failsafe -- / User
 interfaces and core commands *will*, inevitably, fall out of sync.
 What happens then?  Wiki parsers are naturally quite flexible and
 tend to be failsafe (failsafe meaning that a display of an invalid or
 misparsed input file is still likely to be a legible (even if ugly)
 display).   Using Wiki syntax as the protocol between core arch 
 report generators and front ends suggests an interesting approach
 to avoiding needless dependencies between UI and core Arch.

 /Good wiki output is easy and rewarding to produce -- /  Writing
 a plain text report generator that produces wiki-syntax output
 is easy: no special libraries are required;  the basic formatting 
 rules can be learned in just a few minutes.   Wiki output can be 
 attractive *as plain text*, the mark-up actually *contributing*
 to the legibiilty of the output.   So I think that using a wiki
 syntax is a good way to encourage people to concentrate on the
 content and appearence of their reports, rather than on the
 process of trying to implement them.   


 So: I decided I needed a Wiki parser and html translator as a
 building block for `gtla' -- as a component to help build 
 the *programmer's blog* features.

 I have lots of other reasons for wanting such wiki tools.   Not least
 is just to make it easier to produce quick technical communications,
 especially for delivery over the web.

 Being a bit particular about these things, I built the wiki tool that
 formatted the site you're reading now: <"Awiki" --
 ./src/awiki/intro.html>.

 [[cartouche

   \Archive:\ `lord@emf.net--gnu-arch-ws-2004'

   \Location:\ <http://gnuarch.org/archives/lord@emf.net--gnu-arch-ws-2004>

 ]]

** Some Hack Niti-Gritty

*** Interesting Code: `Awiki' contains some neat libraries (additions to `hackerlab')

 The libraries I built for `Awiki' are pretty intereting.

 /`libbufs'/ provides emacs-ish edittable strings.   Programmers can
 create and destroy buffers, store and retrieve per-buffer properties,
 edit and examine the text in the buffer, and allocate and free
 "points" -- pointers into a buffer's string which are adjusted as
 text is inserted or deleted from the string.  `Awiki' works by
 loading its input file into a buffer before processing it.  It
 generates its output in a second buffer before printing anything.


 /`libgraph'/ provides something sort of like buffers, but for
 edittable directed graphs rather than edittable strings.  Programs
 can allocate and free graphs.  Within a graph, programs can create
 and delete nodes and edges and set and retrieve per-node properties.
 `Awiki' uses libgraph to build a parse-tree for its input.


 The implementations of those are, I think, surprisingly simple.
 There are a number of lower level data structures I added first
 (e.g., very simple homogenous queues) --- `libgraph' and `libbufs'
 are built up out of those in just a few steps.

*** C Programming Observation: Descriptors are Better than Pointers

 I've mostly given up on using (data) pointers in structures.  There
 are a few low-level examples where there's no getting around the need
 to have a structure field of some (non-function) pointer type -- but
 mostly I think there are just a few examples of that and they can be 
 solved, once and for all, in a few library modules.

 Without pointers, how can you build a linked list of integer?

 [[tty
	struct int_list
        {
          int elt;
          struct int_list * next;
        };
 ]]

 
 I like using integers, instead.  The type `ssize_t' is usually
 appropriate:

 [[tty
	struct int_list
        {
          int elt;
          ssize_t next;
        };
 ]]

 My approach, though, requires some helper functions:

 [[tty
   /* with pointers:
    */

    struct int_list * list;

    list = list->next;


   /* with integers:
    */

   ssize_t list;

   list = int_list_next (list);

 ]]

 There's more than one way to write something like `int_list_next' and
 which way is right depends on the circumstance.   A fragment of one
 trivial implementation might look like:

 [[tty
	#define int_list_next (list)   list_next_fields[list]
 ]]


 As long as I can find a reasonable way to write accessor and mutator
 functions like `int_list_next', the approach of using integer
 identifiers has some advantages over pointers.

 One big advantage is that the actual object itself can change
 locations in memory.  If the `next' pointers are integer ids, then
 the absolute address of an `int_list' doesn't matter: many memory
 management strategies become simpler.

 Another advantage is that accessor functions like `int_list_next' can
 validate their arguments.  It *is* still possible to use a stale (and
 since recycled) object descriptor with such a function, but there is
 no possibility of attempting to read from an illegal address or
 address containting wrongly typed data.

[[null
  ; arch-tag: Tom Lord Sun Nov 21 19:23:42 2004 (tla-ws/index.txt)
]]

