| Re: makedoc syntax (was Re: [AD] Screen destruction documentation update) |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
> I'm working on an online tool that resembles a Wiki, but is more
> structured. Ie, you can edit pages on the fly, but it knows something
> about function lists, related examples, etc. I fully plan on using it
> to replace a.cc's online Allegro manual, which means the official docs
> would be forked upon launch and not kept in sync.
That's fine in principle. However, I think it would be nice if a list of
changes was forwarded to the mailinglist (as Elias suggested) so that they
could be included in the official docs if we want to. Also, I'm not going
to try to keep documentation that is outside Allegro's `official'
documentation up to date with changes made. For me, it's simply too
bothersome and time consuming to try to keep them synchronised if they're
disjunct.
That's just speaking for me personally though. :)
> It's my belief that the Allegro documentation (if not installation
> related) shouldn't be bundled with Allegro, but just able to be
> downloaded at anytime.
I disagree with this. I absolutely hate it when I have to download
documentation seperately, or worse, can't download it at all.
> This means documentation wouldn't be tied down
> to a particular release of Allegro. (Instead, each individual function
> will be marked with version information - which is useful anyway.)
> People on Windows generally prefer to download a pre-built binary +
> CHM. However, under Linux I think it's quite acceptable (and expected)
> to provide man/info pages with a source library.
Ok, so how about this: the source of the library comes with full
documentation. Binary releases only come with whatever form of
documentation is appropriate for the platform at hand (CHM for Windows,
Mac Help for MacOS X, man+info pages for UNIX).
Evert