Re: makedoc syntax (was Re: [AD] Screen destruction documentation update)

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sat, 2005-09-10 at 11:40 -0500, Matthew Leverton wrote:
> >
> Unless there's one central place to make documentation changes, it
> would be very challenging to keep things in sync. If an a.cc editor
> approves a doc change, but it gets rejected by the Allegro team for
> inclusion in the official docs, it would be out of sync from there on
> forward.

In that case, it also would get removed from the online version.

> If someone from the Allegro team wanted to monitor it and borrow
> changes, that is perfectly fine. Ultimately, I think it could get too
> bothersome to do it, because none of the patches would work on
> makedoc, considering the online manual is in a very wiki-ish format
> and isn't guaranteed to be in sync.

Well, my idea of the new ._tx format is to be this wiki-ish format,
nothng else.

> > There are two things I find most important:
> >
> > 1 Easy editing for developers (at least for me personally, it means an
> > offline text editor, and a wiki-like text format)
> > 2 Easy editing for users (wiki-like web-interface)
> >
> There would be nothing preventing you from exporting the online
> manual, editting the docs off line, and then submiting the changes to
> the site. It would look as if you did it all online. However, I think
> anyone with a dedicated Internet connection (who isn't planning on
> editing documenation while on the road) will much prefer the online
> system if he gives it a fair chance.

This could only work if there was a way to sync my locally exported
version to the online version. Having to re-export it for every change
wouldn't work.

> > 
> I don't expect the Allegro team to use the online docs at all if they
> want to maintain the makedoc approach. It's not their responsibility
> to upkeep an unendorsed manual.
>
> I am totally convinced that it will be a much better system, and that
> a lot of people who would never consider touching makedoc will be
> eager to help out with the documenation. I've heard the argument that
> those people don't exist, but I'm one of them myself. I'd jump at the
> chance to edit something online via instant wiki gratification - but
> when it comes to open up a huge ._tx file with no word wrapping and a
> cryptic syntax, I'll stay away.

Yes, I completely agree. That's the sole reason I started working on a
new makedoc as well.

> I envision scenarios such as: a newbie on a.cc posts a problem
> regarding blit(). A veteran helps him out by linking to the manual and
> explaining something. Someone (perhaps the same person) then takes it
> upon himself to click on the linked blit() function and then click
> "edit" and make a clarification or update to the description. Trusted
> editors then get notified that there is a pending change. Assuming
> it's accepted, it instantly updates the manual and all downloadable
> versions of it - without having to wait a few months (or years) for
> the next Allegro release. That would *never* happen with an offline
> makedoc format. Once people start doing that and seeing themselves get
> credited with doc updates, they may just very will start proactively
> writing documentation.

That's exactly what I'd like to see :) Just, I would have made the
accepting part be [AD] by committing or not committing a patch, instead
of the "a.cc editors" you mentined above.

> I don't want to have a "competing" version of the manual, but I know I
> will never convince the Allegro team if I just don't build it and let
> it speak for itself. :)

Yes, very true. But maybe we could design the new ._tx to already have
the same syntax as that future wiki? I assume, you don't want an editor
where you fill in the type from drop-down boxes and so on, but just a
wiki-like format.

So e.g.:

@@FONT *@extract_font_range(FONT *f, int begin, int end)
@xref get_font_range_begin, get_font_range_end, merge_fonts, transpose_font
@eref exfont
@shortdesc Extracts a range of characters from a font.
   This function extracts a character range from a font and returns a new font
   that contains only the range of characters selected by this function. You
   can pass -1 for either the lower or upper bound if you want to select all
   characters from the start or to the end of the font.
   Example:
<codeblock>
      FONT *myfont;
      FONT *capitals;
      FONT *fontcopy;
      ...
      /* Create a font of only capital letters */
      capitals = extract_font_range(myfont, 'A', 'Z');

      /* Create a copy of the font */
      fontcopy = extract_font_range(myfont, -1, -1);
      ...
      destroy_font(capitals);
      destroy_font(fontcopy);<endblock>
@retval
   Returns a pointer to the new font or NULL on error. Remember that you are
   responsible for destroying the font when you are finished with it to
   avoid memory leaks.


The above is copied out from allegro._tx. Except the mis-matched block
tabs and the manual word-wrapping, it almost could work. The @eref
wouldn't be needed - but everything else would basically be the same:

Specify the function, return value, types. Cross references.
Description. Examples. And everyone would be free to improve it online,
maybe also have a "talk" or "comments" page for it like on wikipedia.

-- 
Elias Pschernig