Re: cross-linking all mentioned source files for API generation?

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=3Dinline *.[ch]
	# This gets a bit wild.  We use ||=3D 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 ||=3D join("|", split("\n", `ls -1 *.[ch]`));' \
            -e '$$fre_dot_escape_done ||=3D ($$frgx =3D~ s/\./\\./g);' \
            -e 's/((?<!\w)(?:$$frgx)(?!\.html|\:\d+))' \
            -e ' /<a href=3D"$$1.html">$$1<\/a>/gx;' \
            *.html
	rm $@/*.[ch]
	rm $@/tags


On Wed, Apr 18, 2012 at 4:17 PM, Britton Kerin <[email protected]> wr=
ote:
> Hi. =A0I'm using source-highlight to generate API docs straight from head=
ers,
> 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. =A0One 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:
> =A0 =A0 =A0 =A0rm -f $@/*.[ch]
> =A0 =A0 =A0 =A0find . -name "*.[ch]" -exec cp \{\} $@ \;
> =A0 =A0 =A0 =A0cd $@ ; source-highlight --gen-references=3Dinline *.[ch]
> =A0 =A0 =A0 =A0# This gets a bit wild. =A0We use ||=3D to take advantage =
of non-lexical
> =A0 =A0 =A0 =A0# vars which aren't reinitialized every time through impli=
cit -p loop,
> =A0 =A0 =A0 =A0# to save prohibitively expensive per-line recomputation o=
f known file
> =A0 =A0 =A0 =A0# name regular expression. =A0The link-for-filename substi=
tution has a
> =A0 =A0 =A0 =A0# negative look-ahead assertion which trims off some file =
name text
> =A0 =A0 =A0 =A0# that source-highlight itself produces.
> =A0 =A0 =A0 =A0cd $@ ; \
> =A0 =A0 =A0 =A0 =A0perl -p -i \
> =A0 =A0 =A0 =A0 =A0 =A0-e '$$fre ||=3D join("|", split("\n", `ls -1 *.[ch=
]`));' \
> =A0 =A0 =A0 =A0 =A0 =A0-e '$$fre_dot_escape_done ||=3D ($$fre =3D~ s/\./\=
\./g);' \
> =A0 =A0 =A0 =A0 =A0 =A0-e 's/((?:$$fre)(?!\.html|\:\d+))/<a href=3D"$$1.h=
tml">$$1<\/a>/g;' \
> =A0 =A0 =A0 =A0 =A0 =A0*.html
> =A0 =A0 =A0 =A0rm $@/*.[ch]
>
> I'm not sure exactly how source-highlight could go about building this so=
rt
> of thing in. =A0Or 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 databa=
se
> entries exist for a symbol) it might be nice to be able to provide some s=
ort
> of explicit disambiguation hint in the sources themselves. =A0The ambigui=
ty
> is or course the result of processing everything together, but other stra=
tegies
> are more complicated. =A0A small feature like this would let you get abou=
t what
> you do from doxygen or the like without having to instrument every functi=
on,
> but only a few in select places for disambiguation.
>
> Just random thoughts.
>
> Britton