On Tue, 28 Dec 2010 12:44:06 +0100 Lionel Orry <lionel.o...@gmail.com> said:
> On Tue, Dec 28, 2010 at 11:03 AM, Carsten Haitzler <ras...@rasterman.com> > wrote: > > On Tue, 28 Dec 2010 09:59:54 +0100 (CET) Vincent Torri <vto...@univ-evry.fr> > > said: > > > >> > that leads to #1. as such developers do hate having to fire up OO to > >> > document things. but as such the things they document are in text anyway > >> > - in the source in javadoc. what i want to know is.. how will these api > >> > docs and such a larger "efl collective" doc work together? do we > >> > perhaps want a way to be able to import the output of doxygen into such > >> > a document nicely? if so.. what about links? doxygen does generate nice > >> > linked documentation where you just mention api_call() and it's a link > >> > to the docs for that call immediately. > >> > >> doxygen can export xml output. So with some xsl scripts, we can do almost > >> what we want. I already did some stuff about that: > >> > >> http://trac.enlightenment.org/e/browser/trunk/DOCS/api/ecrin?rev=44200 > >> > >> Vincent > > You could even avoid the xml output and use the 'doxytag' comments in > the html. Here is a small snippet of bash to create a cross-reference > (example usage: 'efltags.sh <path_to_sources>/ecore/doc/html > > ecore_tags.xml' once doxygen html is generated) > > efltags.sh: > ---------- > #!/bin/sh > echo '<efltags>' > for f in $* > do > bf=$(basename $f) > grep -oE '<!-- doxytag.* -->' $f | > sed 's/<!-- doxytag:/<efltag/' | > sed "s/-->/file=\"$bf\" \/>/;s/ ref=\"/ href=\"$bf#/" | > sed 's/ member="\([^:]*::\)\([^"]*\)"/ short="\2" member="\1 > \2"/' done > echo '</efltags>' > > Then, another snippet to convert the xml output into asciidoc (I made > it only to verify the links. Forget the asciidoc part, it could be any > other processing of course), which uses the xmlstar utility: > > tag2links.sh: > ------------ > #!/bin/sh > PROJECT=$1 > xml sel -t -m "/efltags/eflt...@href]" -o "* > link:\$\$http://docs.enlightenment.org/auto/$PROJECT/"; -v "@href" -o > "\$\$[" -v "@short" -o " (" -v "@member" -o ")]" -n > > That would enable me to do, for example: > > ./efltags.sh ecore/doc/html/*.html | ./tag2links.sh ecore | asciidoc - > > ecore_tags.html > > Maybe including the first snippet to create a cross-reference along > with the html files in docs.e.org/auto/<project>/tags.xml could > provide an easy API to find where is documented one given function of > the EFL. > > > > > oh indeed. i know doxy output xml - i was thinking that... but "then what?". > > how would/could we combine/merge such a thing with OO odt (also xml based.. > > tho not that that is a lot of use here as we'd need to add formatting and > > all sorts of other "odt" inherent information i suspect. > > Maybe OOs macros (python? basic?) may be of use here... Or else, we > should unzip the .odt, modify the xml source with a bit of scripting > and packing it. I suppose it's not harder to apply a named style at > the same time to force a style for this token. before we go deeply down this path - i'd want to see some examples - like taking the eet or eina docs merging them with an odt and making sure styling is ok etc. as well as implementing proper cross-referencing. so before investing a lot of effort - lets try on a small scale and see the results. if we can sanely produce a mega-document that covers all of EFL and properly cross-references etc... then we are getting somewhere. the other option i think about goes back to an earlier discussion of efl docs in the .c vs .h files. - if we move them all to the public api .h files we could run doxygen over all installed headers given a doxyfile and parent "collector" doxy source and basically do it all in doxygen. this would solve all the cross-referencing and put EFL in as a whole into a single linked doc that can easily be on e.org. that's the other option that i see as viable. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ Learn how Oracle Real Application Clusters (RAC) One Node allows customers to consolidate database storage, standardize their database environment, and, should the need arise, upgrade to a full multi-node Oracle RAC database without downtime or disruption http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
