cross-linking all mentioned source files for API generation?

[Britton Kerin]

Hi.  I'm using source-highlight to generate API docs straight from headers,
sort of like Robodoc, doxygen etc but withouth having to mark everything up.
And you can drill down into the sources at need.

This works really nice I think with a few small issues.  One is that it would be
nice to be able to automatically make links from all explicit mentions of source
files. Right now I post-process the generated HTML like this:

# Generate cross linked header and source files as a simple form of API
# documentation (and for browsable source).
.PHONY: xlinked_source_html
xlinked_source_html:
        rm -f $@/*.[ch]
        find . -name "*.[ch]" -exec cp \{\} $@ \;
        cd $@ ; source-highlight --gen-references=inline *.[ch]
        # This gets a bit wild.  We use ||= to take advantage of non-lexical
        # vars which aren't reinitialized every time through implicit -p loop,
        # to save prohibitively expensive per-line recomputation of known file
        # name regular expression.  The link-for-filename substitution has a
        # negative look-ahead assertion which trims off some file name text
        # that source-highlight itself produces.
        cd $@ ; \
          perl -p -i \
            -e '$$fre ||= join("|", split("\n", `ls -1 *.[ch]`));' \
            -e '$$fre_dot_escape_done ||= ($$fre =~ s/\./\\./g);' \
            -e 's/((?:$$fre)(?!\.html|\:\d+))/<a href="$$1.html">$$1<\/a>/g;' \
            *.html
        rm $@/*.[ch]

I'm not sure exactly how source-highlight could go about building this sort
of thing in.  Or maybe it already does and I missed it somehow.

Also, in those cases where source-highlight generates in-line references
to multiple different functions (presumably because multiple ctags database
entries exist for a symbol) it might be nice to be able to provide some sort
of explicit disambiguation hint in the sources themselves.  The ambiguity
is or course the result of processing everything together, but other strategies
are more complicated.  A small feature like this would let you get about what
you do from doxygen or the like without having to instrument every function,
but only a few in select places for disambiguation.

Just random thoughts.

Britton

_______________________________________________
Help-source-highlight mailing list
Help-source-highlight@...
https://lists.gnu.org/mailman/listinfo/help-source-highlight

[Britton Kerin]

Here is a slight refinement to the previous recipe that avoids matches of
partial file names at the trailing end of longer file names:

# Generate cross linked header and source files as a simple form of API
# documentation (and for browsable source).
.PHONY: xlinked_source_html
xlinked_source_html:
        rm -rf $@
        mkdir $@
        find . -name "*.[ch]" -exec cp \{\} $@ \;
        cd $@ ; source-highlight --gen-references=inline *.[ch]
        # This gets a bit wild.  We use ||= to take advantage of non-lexical
        # vars which aren't reinitialized every time through implicit -p loop,
        # to save prohibitively expensive per-line recomputation of known file
        # name regular expression.  The link-for-filename substitution has some
        # negative look-behind and look-ahead assertions which prevent partial
        # file names from matching and trim off some file name text that
        # source-highlight itself produces.
        cd $@ ; \
          perl -p -i \
            -e '$$frgx ||= join("|", split("\n", `ls -1 *.[ch]`));' \
            -e '$$fre_dot_escape_done ||= ($$frgx =~ s/\./\\./g);' \
            -e 's/((?<!\w)(?:$$frgx)(?!\.html|\:\d+))' \
            -e ' /<a href="$$1.html">$$1<\/a>/gx;' \
            *.html
        rm $@/*.[ch]
        rm $@/tags


On Wed, Apr 18, 2012 at 4:17 PM, Britton Kerin <britton.kerin@...> wrote:

> Hi.  I'm using source-highlight to generate API docs straight from headers,
> sort of like Robodoc, doxygen etc but withouth having to mark everything up.
> And you can drill down into the sources at need.
>
> This works really nice I think with a few small issues.  One is that it would be
> nice to be able to automatically make links from all explicit mentions of source
> files. Right now I post-process the generated HTML like this:
>
> # Generate cross linked header and source files as a simple form of API
> # documentation (and for browsable source).
> .PHONY: xlinked_source_html
> xlinked_source_html:
>        rm -f $@/*.[ch]
>        find . -name "*.[ch]" -exec cp \{\} $@ \;
>        cd $@ ; source-highlight --gen-references=inline *.[ch]
>        # This gets a bit wild.  We use ||= to take advantage of non-lexical
>        # vars which aren't reinitialized every time through implicit -p loop,
>        # to save prohibitively expensive per-line recomputation of known file
>        # name regular expression.  The link-for-filename substitution has a
>        # negative look-ahead assertion which trims off some file name text
>        # that source-highlight itself produces.
>        cd $@ ; \
>          perl -p -i \
>            -e '$$fre ||= join("|", split("\n", `ls -1 *.[ch]`));' \
>            -e '$$fre_dot_escape_done ||= ($$fre =~ s/\./\\./g);' \
>            -e 's/((?:$$fre)(?!\.html|\:\d+))/<a href="$$1.html">$$1<\/a>/g;' \
>            *.html
>        rm $@/*.[ch]
>
> I'm not sure exactly how source-highlight could go about building this sort
> of thing in.  Or maybe it already does and I missed it somehow.
>
> Also, in those cases where source-highlight generates in-line references
> to multiple different functions (presumably because multiple ctags database
> entries exist for a symbol) it might be nice to be able to provide some sort
> of explicit disambiguation hint in the sources themselves.  The ambiguity
> is or course the result of processing everything together, but other strategies
> are more complicated.  A small feature like this would let you get about what
> you do from doxygen or the like without having to instrument every function,
> but only a few in select places for disambiguation.
>
> Just random thoughts.
>
> Britton

_______________________________________________
Help-source-highlight mailing list
Help-source-highlight@...
https://lists.gnu.org/mailman/listinfo/help-source-highlight