Re: [E-devel] Proposed new EFL Manual (and some wiki updates)

[Lionel O. <lio...@gm...>]

On Tue, Dec 28, 2010 at 11:03 AM, Carsten Haitzler <ra...@ra...> wrote:
> On Tue, 28 Dec 2010 09:59:54 +0100 (CET) Vincent Torri <vt...@un...>
> 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/efltag[@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.

>
> --
> ------------- Codito, ergo sum - "I code, therefore I am" --------------
> The Rasterman (Carsten Haitzler)    ra...@ra...
>
>

Lionel