Re: [Help-source-highlight] cross-linking all mentioned source files for API generation?

[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 <address@hidden> 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