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
> <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 <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
