XML Editing Tools

GNU Radio
1

Hi.

What are the tools used to create the following Gnu Radio documents:

a) exploring-gnuradio.xml
b) usrp_guide.xml
c) gr-trellis.xml

Best Regards,

Firas

2

I am afraid that the files look hand-written. You can misuse doxygen to
make manuals by feeding it hand written xml. At least I think thats the
case.

I am interested to have a wiki-based markup, where the wiki code could
be rendered into doxygen xml by a small python script (or just strait to
html, it doesnt need to integrate with doxygen).

Its easier to write wiki code than xml, and its easier to maintain
documentation code checked into the git repo (and keep it version
specific).

What do you think about a wiki-based solution to extending gnuradio
documentation?

-Josh

3

On Mon, Apr 12, 2010 at 11:50:56PM -0700, Firas A. wrote:

Hi.

What are the tools used to create the following Gnu Radio documents:

a) exploring-gnuradio.xml
b) usrp_guide.xml
c) gr-trellis.xml

These are DOCBOOK source files (XML).
http://www.docbook.org/whatis

They where written by hand using what ever tools the person writing
them liked. I wrote exploring-gnuradio.xml using xemacs in
“docbook-mode”.

FYI, unlike wiki markup, DOCBOOK source can be compiled into excellent
looking pdfs or html. It’s the standard source file format for Linux
HOWTO’s, as well as lots of other stuff.

http://tldp.org/HOWTO/DocBook-Install/intro.html
http://opensource.bureau-cornavin.com/crash-course

Eric

4

I feel wiki markup is the best way to go. Its friendly on the writer and
makes for readable diffs. I dont like the idea of checking in generated
docbook xml.

We could use restructured text
reStructuredText - Wikipedia and docutils to convert it
to xml, html, etc.

-josh

5

Thank you Josh and Eric for the Responses

From: Josh B. [email protected]

I am afraid that the files look hand-written. You can misuse doxygen to make
manuals by feeding it hand written xml. At least I think thats the case.

Whats I’m looking for is a new approach to generate both html and PDF
documentation from the same source.
I saw that writing an XML document
is the best way since converting from xml to html and pdf is trivial.

Example:

  1. To convert usrp_guide.xml to html file:

    $ xmlto
    html-nochunks usrp_guide.xml

  2. To convert the same file to PDF file:

$ xmlto --with-fop pdf
usrp_guide.xml

Of course , we need the following dependencies:

  • xmlto
  • xmltex
  • fop

I am interested to have a wiki-based markup, where the wiki
code could be rendered into doxygen xml by a small python script (or just
strait to html, it doesnt need to integrate with doxygen).

Its easier to write wiki code than xml, and its easier to maintain
documentation code checked into the git repo (and keep it version specific).

What do you think about a wiki-based solution to extending gnuradio
documentation?

Josh

It is a good idea. If you decided to write such code, please keep in
mined to use redmine wiki markup.

P.S: I want to warn you that I failed to
convert doxygen xml files to PDF files. They seems not to be a standard
docbook xml files.

Best Regards,

Firas