Awesome. It's good to learn there was a patch made. I found a corresponding
thread about the DITA output from Doxygen here:
https://www.linkedin.com/groups/How-can-I-generate-DITA-3709151.S.5890104139333001219
I will have to explore this in the coming days/weeks to evaluate how it all
works. Overall, it's encouraging. As I understand it, the patch works with
version 1.7.4 of Doxygen, and there would need to be some updates made to
the patch to make it work with the latest version of Doxygen. I would
really be interested in helping move this forward. I'm not a developer, so
at most I could perhaps have my company hire dev resources to make the
update. However, I know there's a rift between the DITA world and the API
doc world. This seems to be the most promising bridge.
Tom
---------------------
801-822-2241
blog: idratherbewriting.com
twitter: tomjohnson
On Tue, Oct 7, 2014 at 12:05 PM, Dimitri van Heesch <doxy...@gmail.com>
wrote:
> Hi Tom,
>
> There was a patch made a couple of years ago to add DITA support to
> doxygen, it can still be found here:
> http://sourceforge.net/p/doxygen/mailman/message/27204707/
>
> I haven't integrated it, because I saw very little interest in it so far.
> Maybe you want to help to get it up to date again?
>
> Regards,
> Dimitri
>
> On 07 Oct 2014, at 20:13 , Tom Johnson <tomjohnson1...@gmail.com> wrote:
>
> > You are correct. DITA is an XML standard, not a tool. I use OxygenXML as
> an editor to validate my DITA content. I have explored the HTML to DITA
> transform, and added some notes about using it here (
> http://idratherbewriting.com/ditaqrg/#convert_html_to_dita.html), but
> honestly it's not an easy process. I can guarantee that bulk converting
> Doxygen's HTML output will require some major tweaking of some kind.
> >
> > ---------------------
> > 801-822-2241
> > blog: idratherbewriting.com
> > twitter: tomjohnson
> >
> > On Tue, Oct 7, 2014 at 11:05 AM, Albert <albert.te...@gmail.com> wrote:
> > Tom,
> >
> > As far as I know DITA is a methodology (Darwin Information Typing
> Architecture) and not a tool. The tools I'm aware of are Serna and DITA-OT.
> For the latter wikipedia (http://en.wikipedia.org/wiki/DITA_Open_Toolkit)
> states: It includes a tool for migrating HTML to DITA.
> > Probably this requires that the HTML consists of some "DITA structure"
> though. Did you have look at this?
> >
> > Albert
> >
> > On Tue, Oct 7, 2014 at 7:57 PM, Tom Johnson <tomjohnson1...@gmail.com>
> wrote:
> > I have been exploring two models with DITA. The first model is to import
> source comments directly into DITA (thus not using Doxygen at all). There
> are some DITA plugins that work for Java and C++, but nothing for C#. As
> far as I can tell, the plugins work okay. I haven't explored them too
> deeply other than to verify that the Java one (from Docfacto) appears to
> work, though it may need some cleanup. (Part of the difficulty in assessing
> how it works is that some sections or table rows that are blank may be due
> to poorly formatted source doc rather than the plugin.)
> >
> > The second model is to take the HTML produced from DITA and incorporate
> it into Doxygen's output. I couldn't get this to work, though. Ideally, it
> would be cool if I could export DITA into markdown, but there isn't a
> transform built for that at the moment. Also, although you can convert HTML
> into DITA, it would probably need to be a custom-built transform. The
> default HTML to DITA conversion tools may not auto-process Doxygen's output
> unless you first do some special things to your HTML.
> >
> > I did send the Docbook output from Doxygen to a company called STILO
> that specializes in XML conversions, and asked if they could convert it to
> DITA (because there should be some exchange between Docbook and DITA and
> vice versa). However, they are slow in getting back to me, and so I don't
> have an answer there. My guess is that it will be a custom project
> requiring a lot of time and money.
> >
> > The more I research API documentation, the more fascinating I find it.
> There are some real challenges here, a lot of innovation and variety, and a
> strong need for improvement.
> >
> > Tom
> >
> > ---------------------
> > 801-822-2241
> > blog: idratherbewriting.com
> > twitter: tomjohnson
> >
> > On Tue, Oct 7, 2014 at 10:39 AM, Albert <albert.te...@gmail.com> wrote:
> > Tom,
> >
> > You are talking about DITA, what kind of tools for converting DITA are
> you using / thinking about? Are they able to import e.g. the HTML as
> generated by doxygen or the XML that can be generated by doxygen?
> >
> > Albert
> >
> > On Tue, Oct 7, 2014 at 6:21 PM, Tom Johnson <tomjohnson1...@gmail.com>
> wrote:
> > Thanks for your response. Looking at the document generators as a solved
> problem seems like a okay argument. If the problem were solved 10 yrs ago,
> why is there any need for additional development?
> >
> > Well, technology is rapidly changing, so there are always opportunities
> for enhancements and further development. As I said, of all the document
> generators I've looked at, Doxygen seems to be the most flexible (covering
> many languages), the easiest to use (the GUI front-end tool), and has a
> good-looking output. It also seems the most up to date.
> >
> > I'm mostly frustrated that document generators don't naturally integrate
> with common tech comm authoring structures such as DITA. DITA is probably
> the most common XML authoring standard among professional technical
> writers, but it seems a world apart from document generator tools. I don't
> see why Doxygen can't incorporate simple HTML files into its output.
> >
> > I also don't understand why the majority of web APIs, many of which are
> probably coded using platforms that Doxygen can create documentation for,
> aren't using documentation auto-generated from document generators.
> >
> > Tom
> >
> >
> > ---------------------
> > 801-822-2241
> > blog: idratherbewriting.com
> > twitter: tomjohnson
> >
> > On Tue, Oct 7, 2014 at 5:04 AM, Adam Tauno Williams <
> awill...@whitemice.org> wrote:
> > On Mon, 2014-10-06 at 22:03 -0700, Tom Johnson wrote:
> > > Are document generators for APIs dead? When I look over the possible
> > > options out there, everything seems built about 10 years ago. I don't
> > > see anything new coming out of this genre of tools. I find this odd,
> > > given that APIs themselves are exploding in popularity.
> >
> > Nothing new is required; this is a solved problem. Solved about 10
> > years ago.
> >
> > > I'm guessing that most new APIs today are REST APIs, and none of the
> > > current document generators really address REST?
> >
> > ??? REST APIs are 'theoretically' self-documenting. Which is total BS,
> > but the trope REST fanboys hide behind. Underlying any REST API is code
> > - an API written in source code - that needs to be documented. And that
> > can be accomplished with the same tools.
> > > Can someone clue me in as to why there aren't more recently developed
> > > tools? Doxygen seems to be the best of them, but even Doxygen seems a
> > > bit dated to me.
> >
> > Why is it "dated"? Something that works is not obsolete.
> >
> > --
> > Adam Tauno Williams <mailto:awill...@whitemice.org> GPG D95ED383
> > Systems Administrator, Python Developer, LPI / NCLA
> >
> >
> >
> ------------------------------------------------------------------------------
> > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer
> > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports
> > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper
> > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer
> >
> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk
> > _______________________________________________
> > Doxygen-users mailing list
> > Doxygen-users@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >
> >
> >
> ------------------------------------------------------------------------------
> > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer
> > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports
> > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper
> > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer
> >
> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk
> > _______________________________________________
> > Doxygen-users mailing list
> > Doxygen-users@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
> >
> >
> >
> >
> >
> >
> ------------------------------------------------------------------------------
> > Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer
> > Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports
> > Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper
> > Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer
> >
> http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk_______________________________________________
> > Doxygen-users mailing list
> > Doxygen-users@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>
------------------------------------------------------------------------------
Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer
Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports
Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper
Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer
http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
