On Tue, 14 Mar 2000, George Russell wrote:
> In any case, in the original example
> Who the author is, and what the version is, would be better handled by
> CVS or some similar system. The "<Name>" is redundant; if it doesn't match
> the filename, we have total chaos anyway. The <License> is a drag; I suspect
> it could in fact be dispensed with in most though sadly not all of the civilised
> world, where the presence of a "LICENSE" file in all distributions, or indeed
> nothing at all, will secure automatic legal copyright protection. Of course
> if your lawyers insist I suppose it has to be there . . . <Tested> and
> <Restrictions> would be better handled by referring to a test case file
> somewhere (with the output it's supposed to produce!), then I can see exactly
> (A) what is being tested; (B) whether my new whizz-bang Microsoft Visual
> Haskell compiler can pass these tests.
>
> So my reformed comment would be
> {- Top-level module for HTML combinator library.
> See also test cases in tests/HTML.* and user-level documentation in
> docs/html/HTML.html
> <Other guff, EG places where the code could be speeded up or improved>
> <License, if the lawyers say we've absolutely got to have it here>
> -}
> Of course the user-level documentation does not let the author out of putting
> decent comments in the code as well.
I think one of the major motivation for putting stuff that can be put into
convenient xml form in the files is that with the aid of only the dtd
users can use xml tools to do various machine-aided operations (eg,
finding which bits to read, etc) without worrying about what platform or
tools they're working with. Keeping the name & version in CVS raises the
issue: well what if I don't want to use CVS but rather
RCS/PRCS/bitkeeper/DavesOneOfPerlRevisionControlSystem for some Haskell
files? If everyone's gonna be interoperable then the version control
string that's put into the file has to have a common format, so why not go
for xml. Similarly putting pointers to documents, etc, into a appropriate
entries means that tools can read them but also humans can also read
them. I'm sure it doesn't take more for a human reader to figure out what
`<user-doc>docs/html/HTML.html</user-doc>' means than what `user docs in
docs/html/HTML.html' means.
I know there's a lot of hype about XML & people intersted in dealing with
the bleeding edge, but it does seem to be the most promising way forward
for tackling the problem that the my time is limited and the more I can
quickly, easily & ad-hoc automate the better things will be. I think the
only problems with example intro was that (as is to be expected from a
first attempt) it deals with what the author thinks is important rather
than what reader/users would think is important. Hopefully feedback will
improve the eventual definition of the dtd.
___cheers,_dave________________________________________________________
www.cs.bris.ac.uk/~tweed/pi.htm|ALERT: you are communicating with an
email: [EMAIL PROTECTED] |unsavoury individual with a copy of gdb
work tel: (0117) 954-5253 |who reverse-engineered a file format.
