[docs] xmldocs - docelic modified 7 files

Davor Ocelic docelic at mail.inet.hr
Tue Nov 30 15:50:03 EST 2004


> Ah, ok. Normally we don't use our CVS repository like that -- we only 
> check in work we consider finished. But I guess you've been the only one 
> using the xmldocs repository so far, so had free rein. :)

Yeah :)

> > > I'd like to see the ITL explanation be *extremely* brief. There's a whole 
> > > document, ictags, that explains this stuff in detail. For now, can't we 
> > > just get the user to *use* the tags simply, and follow our tutorial? That 
> > > was the point.
> > 
> > I wanted to move the description out of ictags to iccattut, because the
> > new "incarnation" of ictags are autogenerated reference indexes and
> > there's no place for prose there. And whenever you want to point
> > reader to this section, you can use like <olink doc=iccattut section=tags>.
> 
> I think that would be bad. Any of the reference guides that naturally can
> be organized in alphabetical order should have all the details possible,
> because it'll be easy to find later. The catalog tutorial IMHO shouldn't
> be a reference. Once having read and understood it I should never have to
> look at it again, because now I know what to look for in the truly
> detailed reference docs.
> 
> Why can't we put prose in the autogenerated stuff? You had a way to do
> that for configuration directives, right? I'd rather have the tutorial 
> link to the reference docs than vice versa.

Ah, slight misunderstanding here. You can have prose in descriptions.
I was referring to "introduction to tags" text which is included in
ictags.sdf before the actual tags individually are listed an explained.

That text can't be found at the same location in new ictags-like
documents so I wanted to move it where people would expect it - in
the introductory guide.

> Since you've been doing all the work lately I'm not going to complain a
> ton, but I just wanted to see if we could keep from complicating this
> introductory document and change the direction a little. Don't let me slow
> you down; I'm not going to nitpick your work to death. You're doing
> excellent work.

Okay, I'll adjust iccattut to how it was before this few last commits,
and I'll start adding more symbol descriptions than playing with
iccattut for the moment.

It's been some months of me doing xmldocs now, and I need to start
getting usable results.. 



More information about the docs mailing list