[Dillo-dev] Documentation fixes: autolinking

[Jeremy Henty]

Three small patches that fix autolinking errors in the documentation.
The first two escape the autolinking syntax in a few places where it
was not intended to be a link. The third fixes a few places where a
link was intended but the autolink syntax was not quite right.

http://starurchin.org/dillo/patch/doxygen-escape-hash-characters.html
http://starurchin.org/dillo/patch/doxygen-escape-double-colons.html
http://starurchin.org/dillo/patch/doxygen-fix-simple-name-refs.html

Comments are welcome.

If these are OK I can push them myself as I have write permission.
(It's actually easier for me to do it myself because Mercurial Queues
does not notice when the remote repository has a patch that is
identical to a patch in its queue and generates spurious errors.)

Regards,

Jeremy Henty

_______________________________________________
Dillo-dev mailing list
Dill...@dillo.org
http://lists.dillo.org/cgi-bin/mailman/listinfo/dillo-dev

[Jorge Arellano Cid]

On Mon, Mar 16, 2015 at 03:28:43PM +0000, Jeremy Henty wrote:
>
> Three small patches that fix autolinking errors in the documentation.
> The first two escape the autolinking syntax in a few places where it
> was not intended to be a link. The third fixes a few places where a
> link was intended but the autolink syntax was not quite right.
>
> http://starurchin.org/dillo/patch/doxygen-escape-hash-characters.html
> http://starurchin.org/dillo/patch/doxygen-escape-double-colons.html
> http://starurchin.org/dillo/patch/doxygen-fix-simple-name-refs.html
>
> Comments are welcome.
>
> If these are OK I can push them myself as I have write permission.
> (It's actually easier for me to do it myself because Mercurial Queues
> does not notice when the remote repository has a patch that is
> identical to a patch in its queue and generates spurious errors.)

+1.

Just not sure about the last one. I don't know whether it
changes the intended semantic for human readers.

--
Cheers
Jorge.-

[Jeremy Henty]

Jorge Arellano Cid wrote:

> On Mon, Mar 16, 2015 at 03:28:43PM +0000, Jeremy Henty wrote:
> >
> > Three small patches that fix autolinking errors in the documentation.
> > The first two escape the autolinking syntax in a few places where it
> > was not intended to be a link. The third fixes a few places where a
> > link was intended but the autolink syntax was not quite right.
> >
> > http://starurchin.org/dillo/patch/doxygen-escape-hash-characters.html
> > http://starurchin.org/dillo/patch/doxygen-escape-double-colons.html
> > http://starurchin.org/dillo/patch/doxygen-fix-simple-name-refs.html
> >
> > Comments are welcome.
> >
> > If these are OK I can push them myself as I have write permission.
> > (It's actually easier for me to do it myself because Mercurial Queues
> > does not notice when the remote repository has a patch that is
> > identical to a patch in its queue and generates spurious errors.)
>
> +1.
>
> Just not sure about the last one. I don't know whether it
> changes the intended semantic for human readers.

I think it actually corrects the semantics. An initial '::' means
resolve the name in the top namespace, not the current one, but the
class names used in the docs are relative to dw/lout. So I think the
patch does the right thing.

Regards,

Jeremy Henty

[Jeremy Henty]

I wrote:

> Jorge Arellano Cid wrote:
>
> > On Mon, Mar 16, 2015 at 03:28:43PM +0000, Jeremy Henty wrote:
> > >
> > > Three small patches that fix autolinking errors in the documentation.
> > > The first two escape the autolinking syntax in a few places where it
> > > was not intended to be a link. The third fixes a few places where a
> > > link was intended but the autolink syntax was not quite right.
> > >
> > > http://starurchin.org/dillo/patch/doxygen-escape-hash-characters.html
> > > http://starurchin.org/dillo/patch/doxygen-escape-double-colons.html
> > > http://starurchin.org/dillo/patch/doxygen-fix-simple-name-refs.html
> > >
> > > Comments are welcome.
> > >
> > > If these are OK I can push them myself as I have write permission.
> > > (It's actually easier for me to do it myself because Mercurial Queues
> > > does not notice when the remote repository has a patch that is
> > > identical to a patch in its queue and generates spurious errors.)
> >
> > +1.
> >
> > Just not sure about the last one. I don't know whether it
> > changes the intended semantic for human readers.
>
> I think it actually corrects the semantics. An initial '::' means
> resolve the name in the top namespace, not the current one, but the
> class names used in the docs are relative to dw/lout. So I think the
> patch does the right thing.

Bump! Is it OK for me to push these or is more discussion needed?

[Sebastian Geerken]

Sorry for the late response.

On Sa, Apr 04, 2015, Jeremy Henty wrote:
>
> I wrote:
>
> > Jorge Arellano Cid wrote:
> >
> > > On Mon, Mar 16, 2015 at 03:28:43PM +0000, Jeremy Henty wrote:
> > > >
> > > > Three small patches that fix autolinking errors in the documentation.
> > > > The first two escape the autolinking syntax in a few places where it
> > > > was not intended to be a link. The third fixes a few places where a
> > > > link was intended but the autolink syntax was not quite right.
> > > >
> > > > http://starurchin.org/dillo/patch/doxygen-escape-hash-characters.html
> > > > http://starurchin.org/dillo/patch/doxygen-escape-double-colons.html
> > > > http://starurchin.org/dillo/patch/doxygen-fix-simple-name-refs.html
> > > >
> > > > Comments are welcome.
> > > >
> > > > If these are OK I can push them myself as I have write permission.
> > > > (It's actually easier for me to do it myself because Mercurial Queues
> > > > does not notice when the remote repository has a patch that is
> > > > identical to a patch in its queue and generates spurious errors.)
> > >
> > > +1.
> > >
> > > Just not sure about the last one. I don't know whether it
> > > changes the intended semantic for human readers.
> >
> > I think it actually corrects the semantics. An initial '::' means
> > resolve the name in the top namespace, not the current one, but the
> > class names used in the docs are relative to dw/lout. So I think the
> > patch does the right thing.
>
> Bump! Is it OK for me to push these or is more discussion needed?

Haven't yet tested them, but they look OK; so push them if they don't
break anything.

As for "::" vs. "\ref": I added "::" to have a reference at all. I'm
not sure about the exact rules, but Doxygen seems to regard anything
containing "::" as reference.

If "\ref" works, it looks cleaner IMO.

Sebastian

[Jeremy Henty]

OK, it is done.

> As for "::" vs. "\ref": I added "::" to have a reference at all. I'm
> not sure about the exact rules, but Doxygen seems to regard anything
> containing "::" as reference.
>
> If "\ref" works, it looks cleaner IMO.

I agree.