Re: [Doxygen-users] are document generators dead?

[Albert <alb...@gm...>]

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