Re: adding IR links

[John Mandereau]

Graham Percival wrote:
> On Fri, 4 Apr 2008 20:11:40 +0200
> "Valentin Villenave" <address@hidden> wrote:
> 
> > We need to be careful with these references, that can get outdated
> > very quickly (for instance, the text-balloon-interface has now become
> > the balloon-interface and therefore the link was broken).

Maybe convert-ly should handle this kind of conversion (see below); to
be more explicit, maybe we forgot to add a convert-ly rule (which would
have handled this conversion) for this rename.


> Well, maybe not.  Project for your consideration, John:
> 
> Add a dedicated "documentation" mode for convert-ly.  This would
> automatically do things like --from --to.  And more importantly,
> it would look for
> @internalsref{\foo}
> @code{\foo}
> and automatically update those to \bar (if a convert-ly rule
> exists for such a thing)
> 
> (instead of a "dedicated" doc mode for convert-ly, perhaps adding
> more command-line options, and then dumping a script in
> buildscripts/convert-docs would be better...

All this is bloody ;-) complicated.  As I already wrote in my other
reply in this thread, convert-ly greedily replaces all regexps matches;
for example convert-ly updated command names in the running text in
commit 4b7ee2775e308ded9f12976cb3ccd2c184d8aadd.

The actual issue is whether we want to add a convert-ly rule for each
grob or internal property rename, e.g.
text-balloon-interface->balloon-interface.  Not all changes in property
names can be processed by convert-ly, but certainly more could be
handled.


>  for that matter, I'm
> also not comfortable with the \version string in
> fundamental.itely; we should have a LAST-VERSION or some such file
> in Documentatation/  which the convert-docs script would
> automatically updated)

I added "@c \version" to all .itelys, which definitely solves this
problem.

@off-topic
Gee, either sed is broken, or the manual doesn't match sed features, or
I'm stupid: 's/@end ignore/&address@hidden \\version "2.11.38"/1' inserts the
\version line after all occurences of '@end ignore', despite of the '1'
flag telling sed to replace only first match.  I was only able to do
this line insertion properly from a Python prompt.  I'll report this
problem to sed user list or maintainers.
@end off-topic

Cheers,
John