Re: [Doxygen-users] are document generators dead?
Brought to you by:
dimitri
Menu
▾
▴
Re: [Doxygen-users] are document generators dead?
|
From: Tom J. <tom...@gm...> - 2014-10-07 18:13:42
|
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 <alb...@gm...> 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 > <http://en.wikipedia.org/wiki/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 <tom...@gm...> > 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 <alb...@gm...> 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 <tom...@gm...> >>> 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 < >>>> awi...@wh...> 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:awi...@wh...> 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 >>>>> Dox...@li... >>>>> 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 >>>> Dox...@li... >>>> https://lists.sourceforge.net/lists/listinfo/doxygen-users >>>> >>>> >>> >> > |
