Loading ...
Sorry, an error occurred while loading the content.

Re: [xml-doc] Has anyone tried to integrate Doxygen Output with Structured Framemaker

Expand Messages
  • Isaac Rabinovitch
    ... Doxygen can output to XML. This feature is listed as under development , and it is pretty crude. But probably preferrable to dealing with HTML.
    Message 1 of 14 , Dec 30, 2005
    • 0 Attachment
      Alan Houser wrote:

      >You will need to convert one of Doxygen's output formats (HTML,
      >presumably) to valid XML.
      >
      Doxygen can output to XML. This feature is listed as "under
      development", and it is pretty crude. But probably preferrable to
      dealing with HTML.
    • Charles Johnston
      Hi Alok, Why do you even want to do this, I wonder? We use structured FM to produce PDF documentation, and produce HTML-based API documentation using Doxygen,
      Message 2 of 14 , Jan 2, 2006
      • 0 Attachment
        Hi Alok,

        Why do you even want to do this, I wonder?

        We use structured FM to produce PDF documentation, and produce HTML-based
        API documentation using Doxygen, but we have never seen any reason to want
        to import API material into Frame. The API stuff will be used by developers
        and I doubt they will want hard-copy API documentation, which seems to be
        the only added-value Frame can offer. XML offers structure, but what use
        does the structure have? The API stuff is already structured in the source
        code, so why restructure it in Frame?

        Why not just stick with HTML? You can add graphics there simply enough.

        Or is this something to do with conditionality? If you don't want to include
        all the API stuff, you can simply make several Doxygen extraction jobs and
        then combine the sets of HTML as you choose.

        Charles


        >From: "alokndel" <tuxwarrior@...>
        >Reply-To: xml-doc@yahoogroups.com
        >To: xml-doc@yahoogroups.com
        >Subject: [xml-doc] Has anyone tried to integrate Doxygen Output with
        >Structured Framemaker
        >Date: Fri, 30 Dec 2005 10:06:47 -0000
        >
        >Hi
        >
        >I'm writing this email to get suggestions from content management
        >experts in this forum. I'm trying to set up a tagging framework in
        >my company so that API document is generated straight from the
        >source code. My API document contains graphics and customized
        >formatting. It also contains conditional text so that I can generate
        >different versions of the API document for internal folks and
        >customers.
        >
        >What I'm trying to develop will work like this...
        >
        >1. Software developers tag the source code for API data
        >(Description, Parameters, Return Value etc.)
        >2. A PERL script parses the source code for API data and formats
        >this data into an XML file. The PERL script adds a unique ID for
        >each API, for example if there are two APIs "A" and "B". The PERL
        >script tags the API with A and B respectively.
        >3. The output of the PERL script maps to a customized DTD. This
        >customized DTD is the glue that binds the API document (in
        >Structured Framemaker) to the output of the PERL script.
        >4. Everytime the source code is modified, the PERL script kicks off
        >and generates a new XML file. Since this XML file maps to the
        >customized DTD and Framemaker is able to import the new data and the
        >API document stays updated.
        >5. The framework allows me to insert graphics in the Framemaker
        >document in between the API data that I've got from the PERL script.
        >6. Framemaker allows me to use conditional text and provides me all
        >the publishing tools that I need to spruce up my API.
        >
        >Do you think this process will work? What has been your experience
        >in handling similar situations?
        >
        >Best regards,
        >Alok
        >
        >
        >
        >
        >
        >
        >Yahoo! Groups Links
        >
        >
        >
        >
        >
        >
      • peterm@zeta.org.au
        alokndel: ... I ve been using similar procedures for different varieties of technical programming documentation for some time, but at a time when importing of
        Message 3 of 14 , Jan 2, 2006
        • 0 Attachment
          alokndel:
          On Fri, 30 Dec 2005 10:06:47 -0000, you wrote:
          > Hi
          >
          > I'm writing this email to get suggestions from content
          > management experts in this forum. I'm trying to set up a
          > tagging framework in my company so that API document is
          > generated straight from the source code. My API document
          > contains graphics and customized formatting. It also contains
          > conditional text so that I can generate different versions of
          > the API document for internal folks and customers.
          >
          > What I'm trying to develop will work like this...
          >
          > 1. Software developers tag the source code for API data
          > (Description, Parameters, Return Value etc.)
          > 2. A PERL script parses the source code for API data and
          > formats this data into an XML file. The PERL script adds a
          > unique ID for each API, for example if there are two APIs "A"
          > and "B". The PERL script tags the API with A and B
          > respectively.
          > 3. The output of the PERL script maps to a customized DTD.
          > This customized DTD is the glue that binds the API document
          > (in Structured Framemaker) to the output of the PERL script.
          > 4. Everytime the source code is modified, the PERL script
          > kicks off and generates a new XML file. Since this XML file
          > maps to the customized DTD and Framemaker is able to import
          > the new data and the API document stays updated.
          > 5. The framework allows me to insert graphics in the
          > Framemaker document in between the API data that I've got from
          > the PERL script.
          > 6. Framemaker allows me to use conditional
          > text and provides me all the publishing tools that I need to
          > spruce up my API.
          >
          > Do you think this process will work? What has been your
          > experience in handling similar situations?
          >

          I've been using similar procedures for different varieties of technical
          programming documentation for some time, but at a time when importing of
          various different formats into FrameMaker was very limited, it was actually
          easier to set up a MIF template. I insert various key information items using
          Perl regexes and target markers in the MIF template, and then automate the
          opening and saving of the FrameMaker MIF files into the FrameMaker binaries
          and/or other formats using generated batch files which were used by the
          dzbatcher tool.

          Graphics can be inserted with Anchored Frames and inserted import references.

          Alternatively, I've used XHTML importing on occasions (ensuring compliance by
          running HTML-Tidy over initially-generated HTML helps, here).

          I've yet to be fully convinced that FM 7.2 will do what I plan later with DTDs
          and XML, so I'm planning to vary or combine these approaches to get to XML
          eventually for my own purposes.

          If you head anywhere in this direction, feel free to contact me for some Perl
          snippets that may be of assistance...

          And for those who query the need for hard copy of API documentation (without
          necessarily handing over all source code at the same time) -- we have customers
          who appreciate the availability of some Public APIs and documentation on them
          to allow local customization of an extensible (plug-in oriented) product, and
          providing PDFs or somesuch is not just appreciated, but often demanded...
          Examples would include the provision of details of required parameters, their
          types and ranges etc for publicly accessible APIs...

          Some years ago I recall it was particularly important for example, for a gaming
          site where government regulators insisted on being able to examine technical
          documentation without having to pick through the whole codebase. In once case,
          several thousand pages of documentation was built with the code in each build to
          maintain key parameter details, default values etc... Eventually, it was just
          easier than slashing through Javadoc etc.. And a little earlier, I had
          similar stuff working with Doxygen on critical SCADA C++ code, so yep, much is
          possible and often worth it.

          (This is called Tech writing... :-) Unfortunately, it's paid that way... )

          --Peter M
        • Charles Johnston
          ... You re clearly not familiar with Doxygen. Doxygen only extracts text that is marked up to be extracted. The source code is not included, for obvious
          Message 4 of 14 , Jan 2, 2006
          • 0 Attachment
            >(without necessarily handing over all source code at the same time)
            >being able to examine technical documentation without having to pick
            >through the whole codebase

            You're clearly not familiar with Doxygen. Doxygen only extracts text that is
            marked up to be extracted. The source code is not included, for obvious
            reasons.

            Even if a printed copy is required, I still don't see why you would want to
            restructure it to produce a hard-copy. You cannot reuse/extract structure
            from a hard-copy. So you would only want to restructure it if you were going
            to use it electronically for some other purpose. And if HTML isn't good
            enough, I'm wondering what that other purpose might be.

            Charles

            >From: peterm@...
            >Reply-To: xml-doc@yahoogroups.com
            >To: xml-doc@yahoogroups.com
            >Subject: Re: [xml-doc] Has anyone tried to integrate Doxygen Output
            >withStructured Framemaker
            >Date: Mon, 02 Jan 2006 22:42:19 +1100
            >
            >alokndel:
            >On Fri, 30 Dec 2005 10:06:47 -0000, you wrote:
            > > Hi
            > >
            > > I'm writing this email to get suggestions from content
            > > management experts in this forum. I'm trying to set up a
            > > tagging framework in my company so that API document is
            > > generated straight from the source code. My API document
            > > contains graphics and customized formatting. It also contains
            > > conditional text so that I can generate different versions of
            > > the API document for internal folks and customers.
            > >
            > > What I'm trying to develop will work like this...
            > >
            > > 1. Software developers tag the source code for API data
            > > (Description, Parameters, Return Value etc.)
            > > 2. A PERL script parses the source code for API data and
            > > formats this data into an XML file. The PERL script adds a
            > > unique ID for each API, for example if there are two APIs "A"
            > > and "B". The PERL script tags the API with A and B
            > > respectively.
            > > 3. The output of the PERL script maps to a customized DTD.
            > > This customized DTD is the glue that binds the API document
            > > (in Structured Framemaker) to the output of the PERL script.
            > > 4. Everytime the source code is modified, the PERL script
            > > kicks off and generates a new XML file. Since this XML file
            > > maps to the customized DTD and Framemaker is able to import
            > > the new data and the API document stays updated.
            > > 5. The framework allows me to insert graphics in the
            > > Framemaker document in between the API data that I've got from
            > > the PERL script.
            > > 6. Framemaker allows me to use conditional
            > > text and provides me all the publishing tools that I need to
            > > spruce up my API.
            > >
            > > Do you think this process will work? What has been your
            > > experience in handling similar situations?
            > >
            >
            >I've been using similar procedures for different varieties of technical
            >programming documentation for some time, but at a time when importing of
            >various different formats into FrameMaker was very limited, it was actually
            >easier to set up a MIF template. I insert various key information items
            >using
            >Perl regexes and target markers in the MIF template, and then automate the
            >opening and saving of the FrameMaker MIF files into the FrameMaker binaries
            >and/or other formats using generated batch files which were used by the
            >dzbatcher tool.
            >
            >Graphics can be inserted with Anchored Frames and inserted import
            >references.
            >
            >Alternatively, I've used XHTML importing on occasions (ensuring compliance
            >by
            >running HTML-Tidy over initially-generated HTML helps, here).
            >
            >I've yet to be fully convinced that FM 7.2 will do what I plan later with
            >DTDs
            >and XML, so I'm planning to vary or combine these approaches to get to XML
            >eventually for my own purposes.
            >
            >If you head anywhere in this direction, feel free to contact me for some
            >Perl
            >snippets that may be of assistance...
            >
            >And for those who query the need for hard copy of API documentation
            >(without
            >necessarily handing over all source code at the same time) -- we have
            >customers
            >who appreciate the availability of some Public APIs and documentation on
            >them
            >to allow local customization of an extensible (plug-in oriented) product,
            >and
            >providing PDFs or somesuch is not just appreciated, but often demanded...
            >Examples would include the provision of details of required parameters,
            >their
            >types and ranges etc for publicly accessible APIs...
            >
            >Some years ago I recall it was particularly important for example, for a
            >gaming
            >site where government regulators insisted on being able to examine
            >technical
            >documentation without having to pick through the whole codebase. In once
            >case,
            >several thousand pages of documentation was built with the code in each
            >build to
            >maintain key parameter details, default values etc... Eventually, it was
            >just
            >easier than slashing through Javadoc etc.. And a little earlier, I had
            >similar stuff working with Doxygen on critical SCADA C++ code, so yep, much
            >is
            >possible and often worth it.
            >
            >(This is called Tech writing... :-) Unfortunately, it's paid that way...
            >)
            >
            >--Peter M
            >
            >
            >
            >
            >
            >
            >
            >
            >
            >Yahoo! Groups Links
            >
            >
            >
            >
            >
            >
          • Isaac Rabinovitch
            ... You re wrong about that. Strange but true. I ve worked on documentation for truly massive APIs (tens of thousands of individual calls). It never made sense
            Message 5 of 14 , Jan 2, 2006
            • 0 Attachment
              Charles Johnston wrote:

              > The API stuff will be used by developers
              >and I doubt they will want hard-copy API documentation, which seems to be
              >the only added-value Frame can offer.
              >
              You're wrong about that. Strange but true. I've worked on documentation
              for truly massive APIs (tens of thousands of individual calls). It never
              made sense to me that anybody would want a hard copy version of the
              documentation. Why spend $500 to $1000 for a set of books that are less
              convenient to access than online docs (especially if you have an IDE
              with context-sensitive help) and that will be obsolete in a year? But
              people want them. I've never been able to understand why, but they do.
            • peterm@zeta.org.au
              Charles Johnston: On Mon, 02 Jan 2006 12:05:56 +0000, you ... For a start, I d appreciate it if you didn t quote me out of context and make indjudicious and
              Message 6 of 14 , Jan 2, 2006
              • 0 Attachment
                Charles Johnston: On Mon, 02 Jan 2006 12:05:56 +0000, you
                wrote:
                >> (without necessarily handing over all source code at the same
                >> time) being able to examine technical documentation without
                >> having to pick through the whole codebase
                >>
                >
                > You're clearly not familiar with Doxygen. Doxygen only
                > extracts text that is marked up to be extracted. The source
                > code is not included, for obvious reasons.
                >


                For a start, I'd appreciate it if you didn't quote me out of context and make
                indjudicious and prejudicial snips without specifying your edits.

                Into the bargain, I'd rather you didn't call me a liar.

                Actually, what I said is cited below in full, but here's the relevant bit:

                >> And for those who query the need for hard copy of API
                >> documentation (without necessarily handing over all source
                >> code at the same time) -- we have customers who appreciate
                >> the availability of some Public APIs and documentation on
                >> them to allow local customization of an extensible (plug-in
                >> oriented) product, and providing PDFs or somesuch is not just
                >> appreciated, but often demanded... Examples would include the
                >> provision of details of required parameters, their types and
                >> ranges etc for publicly accessible APIs...
                >>
                >> Some years ago I recall it was particularly important for
                >> example, for a gaming site where government regulators
                >> insisted on being able to examine technical documentation
                >> without having to pick through the whole codebase. In once
                >> case, several thousand pages of documentation was built with
                >> the code in each build to maintain key parameter details,
                >> default values etc... Eventually, it was just easier than
                >> slashing through Javadoc etc.. And a little earlier, I had
                >> similar stuff working with Doxygen on critical SCADA C++
                >> code, so yep, much is possible and often worth it.
                >>

                From this you may gather:

                a.) that I've worked with Doxygen.

                b.) that I wasn't discusssing Doxygen alone.

                In any event, Doxygen meets the specs: hard copy from Doxygen output provides
                API documentation without handing over the code.


                > Even if a printed copy is required, I still don't see why you
                > would want to restructure it to produce a hard-copy. You
                > cannot reuse/extract structure from a hard-copy. So you would
                > only want to restructure it if you were going to use it
                > electronically for some other purpose. And if HTML isn't good
                > enough, I'm wondering what that other purpose might be.

                You restructure it to produce hard copy because some customers -- including some
                global giants -- like it that way, ask for it that way, contract to have it
                delivered that way etc...

                You clearly haven't worked with some of these customers. But they exist in
                significant numbers, and many simply don't like HTML alone. In our case, we
                find it useful these days to bundle the documentation with included code
                example files built into the PDF for easy extraction.


                --Peter M


                >> From: peterm@... Reply-To: xml-doc@yahoogroups.com
                >> To: xml-doc@yahoogroups.com Subject: Re: [xml-doc] Has anyone
                >> tried to integrate Doxygen Output withStructured Framemaker
                >> Date: Mon, 02 Jan 2006 22:42:19 +1100
                >>
                <snipped original email>

                >>
                >> I've been using similar procedures for different varieties of
                >> technical programming documentation for some time, but at a
                >> time when importing of various different formats into
                >> FrameMaker was very limited, it was actually easier to set
                >> up a MIF template. I insert various key information items
                >> using Perl regexes and target markers in the MIF template,
                >> and then automate the opening and saving of the FrameMaker
                >> MIF files into the FrameMaker binaries and/or other formats
                >> using generated batch files which were used by the dzbatcher
                >> tool.
                >>
                >> Graphics can be inserted with Anchored Frames and inserted
                >> import references.
                >>
                >> Alternatively, I've used XHTML importing on occasions
                >> (ensuring compliance by running HTML-Tidy over initially-
                >> generated HTML helps, here).
                >>
                >> I've yet to be fully convinced that FM 7.2 will do what I
                >> plan later with DTDs and XML, so I'm planning to vary or
                >> combine these approaches to get to XML eventually for my own
                >> purposes.
                >>
                >> If you head anywhere in this direction, feel free to contact
                >> me for some Perl snippets that may be of assistance...
                >>
                >> And for those who query the need for hard copy of API
                >> documentation (without necessarily handing over all source
                >> code at the same time) -- we have customers who appreciate
                >> the availability of some Public APIs and documentation on
                >> them to allow local customization of an extensible (plug-in
                >> oriented) product, and providing PDFs or somesuch is not just
                >> appreciated, but often demanded... Examples would include the
                >> provision of details of required parameters, their types and
                >> ranges etc for publicly accessible APIs...
                >>
                >> Some years ago I recall it was particularly important for
                >> example, for a gaming site where government regulators
                >> insisted on being able to examine technical documentation
                >> without having to pick through the whole codebase. In once
                >> case, several thousand pages of documentation was built with
                >> the code in each build to maintain key parameter details,
                >> default values etc... Eventually, it was just easier than
                >> slashing through Javadoc etc.. And a little earlier, I had
                >> similar stuff working with Doxygen on critical SCADA C++
                >> code, so yep, much is possible and often worth it.
                >>
              • peterm@zeta.org.au
                Oops. For indjudicious , read injudicious . The dj combination probably resulted from gnashing of the teeth... --Peter M
                Message 7 of 14 , Jan 2, 2006
                • 0 Attachment
                  Oops. For "indjudicious", read "injudicious". The "dj" combination probably
                  resulted from gnashing of the teeth...

                  --Peter M
                • Charles Johnston
                  Well, I certainly don t know how you figure out that I called you a liar. If I gave that impression, that was certainly injudicious. Hope your teeth are still
                  Message 8 of 14 , Jan 2, 2006
                  • 0 Attachment
                    Well, I certainly don't know how you figure out that I called you a liar. If
                    I gave that impression, that was certainly injudicious. Hope your teeth are
                    still OK. My apologies for suggesting you weren't familiar with Doxygen - I
                    skimmed your e-mail and didn't read it as closely as I should have.

                    Help me here, I am simply wondering why "many simply don't like HTML alone".
                    I note when you say customers "like it that way, ask for it that way,
                    contract to have it delivered that way etc." that you didn't specifically
                    add "need it that way". We aren't producing XML-based API documentation
                    because we don't see a need, but maybe we should be doing this for a reason
                    I haven't seen, in which case I would be grateful for elucidation!

                    What are they getting from API documentation in XML that they aren't getting
                    in HTML? What is the added value to them?

                    Humbly.

                    Charles

                    >From: peterm@...
                    >Reply-To: xml-doc@yahoogroups.com
                    >To: xml-doc@yahoogroups.com
                    >Subject: Re: [xml-doc] Has anyone tried to integrate Doxygen
                    >OutputwithStructured Framemaker
                    >Date: Tue, 03 Jan 2006 09:08:43 +1100
                    >
                    >Charles Johnston: On Mon, 02 Jan 2006 12:05:56 +0000, you
                    >wrote:
                    > >> (without necessarily handing over all source code at the same
                    > >> time) being able to examine technical documentation without
                    > >> having to pick through the whole codebase
                    > >>
                    > >
                    > > You're clearly not familiar with Doxygen. Doxygen only
                    > > extracts text that is marked up to be extracted. The source
                    > > code is not included, for obvious reasons.
                    > >
                    >
                    >
                    >For a start, I'd appreciate it if you didn't quote me out of context and
                    >make
                    >indjudicious and prejudicial snips without specifying your edits.
                    >
                    >Into the bargain, I'd rather you didn't call me a liar.
                    >
                    >Actually, what I said is cited below in full, but here's the relevant bit:
                    >
                    > >> And for those who query the need for hard copy of API
                    > >> documentation (without necessarily handing over all source
                    > >> code at the same time) -- we have customers who appreciate
                    > >> the availability of some Public APIs and documentation on
                    > >> them to allow local customization of an extensible (plug-in
                    > >> oriented) product, and providing PDFs or somesuch is not just
                    > >> appreciated, but often demanded... Examples would include the
                    > >> provision of details of required parameters, their types and
                    > >> ranges etc for publicly accessible APIs...
                    > >>
                    > >> Some years ago I recall it was particularly important for
                    > >> example, for a gaming site where government regulators
                    > >> insisted on being able to examine technical documentation
                    > >> without having to pick through the whole codebase. In once
                    > >> case, several thousand pages of documentation was built with
                    > >> the code in each build to maintain key parameter details,
                    > >> default values etc... Eventually, it was just easier than
                    > >> slashing through Javadoc etc.. And a little earlier, I had
                    > >> similar stuff working with Doxygen on critical SCADA C++
                    > >> code, so yep, much is possible and often worth it.
                    > >>
                    >
                    >From this you may gather:
                    >
                    >a.) that I've worked with Doxygen.
                    >
                    >b.) that I wasn't discusssing Doxygen alone.
                    >
                    >In any event, Doxygen meets the specs: hard copy from Doxygen output
                    >provides
                    >API documentation without handing over the code.
                    >
                    >
                    > > Even if a printed copy is required, I still don't see why you
                    > > would want to restructure it to produce a hard-copy. You
                    > > cannot reuse/extract structure from a hard-copy. So you would
                    > > only want to restructure it if you were going to use it
                    > > electronically for some other purpose. And if HTML isn't good
                    > > enough, I'm wondering what that other purpose might be.
                    >
                    >You restructure it to produce hard copy because some customers -- including
                    >some
                    >global giants -- like it that way, ask for it that way, contract to have it
                    >delivered that way etc...
                    >
                    >You clearly haven't worked with some of these customers. But they exist
                    >in
                    >significant numbers, and many simply don't like HTML alone. In our case, we
                    >find it useful these days to bundle the documentation with included code
                    >example files built into the PDF for easy extraction.
                    >
                    >
                    >--Peter M
                    >
                    >
                    > >> From: peterm@... Reply-To: xml-doc@yahoogroups.com
                    > >> To: xml-doc@yahoogroups.com Subject: Re: [xml-doc] Has anyone
                    > >> tried to integrate Doxygen Output withStructured Framemaker
                    > >> Date: Mon, 02 Jan 2006 22:42:19 +1100
                    > >>
                    ><snipped original email>
                    >
                    > >>
                    > >> I've been using similar procedures for different varieties of
                    > >> technical programming documentation for some time, but at a
                    > >> time when importing of various different formats into
                    > >> FrameMaker was very limited, it was actually easier to set
                    > >> up a MIF template. I insert various key information items
                    > >> using Perl regexes and target markers in the MIF template,
                    > >> and then automate the opening and saving of the FrameMaker
                    > >> MIF files into the FrameMaker binaries and/or other formats
                    > >> using generated batch files which were used by the dzbatcher
                    > >> tool.
                    > >>
                    > >> Graphics can be inserted with Anchored Frames and inserted
                    > >> import references.
                    > >>
                    > >> Alternatively, I've used XHTML importing on occasions
                    > >> (ensuring compliance by running HTML-Tidy over initially-
                    > >> generated HTML helps, here).
                    > >>
                    > >> I've yet to be fully convinced that FM 7.2 will do what I
                    > >> plan later with DTDs and XML, so I'm planning to vary or
                    > >> combine these approaches to get to XML eventually for my own
                    > >> purposes.
                    > >>
                    > >> If you head anywhere in this direction, feel free to contact
                    > >> me for some Perl snippets that may be of assistance...
                    > >>
                    > >> And for those who query the need for hard copy of API
                    > >> documentation (without necessarily handing over all source
                    > >> code at the same time) -- we have customers who appreciate
                    > >> the availability of some Public APIs and documentation on
                    > >> them to allow local customization of an extensible (plug-in
                    > >> oriented) product, and providing PDFs or somesuch is not just
                    > >> appreciated, but often demanded... Examples would include the
                    > >> provision of details of required parameters, their types and
                    > >> ranges etc for publicly accessible APIs...
                    > >>
                    > >> Some years ago I recall it was particularly important for
                    > >> example, for a gaming site where government regulators
                    > >> insisted on being able to examine technical documentation
                    > >> without having to pick through the whole codebase. In once
                    > >> case, several thousand pages of documentation was built with
                    > >> the code in each build to maintain key parameter details,
                    > >> default values etc... Eventually, it was just easier than
                    > >> slashing through Javadoc etc.. And a little earlier, I had
                    > >> similar stuff working with Doxygen on critical SCADA C++
                    > >> code, so yep, much is possible and often worth it.
                    > >>
                    >
                    >
                    >
                    >Yahoo! Groups Links
                    >
                    >
                    >
                    >
                    >
                    >
                  • Alok Narula
                    All: I really appreciate the knowledge and wisdom that you ve shared in response to my email. The reason why I want to generate XML output from my source code
                    Message 9 of 14 , Jan 3, 2006
                    • 0 Attachment
                      All:

                      I really appreciate the knowledge and wisdom that you've shared in response
                      to my email.

                      The reason why I want to generate XML output from my source code is because
                      I want to use the data captured from the source code for different
                      consumers: API users, API testers, and Integrated Development Editors (IDE).
                      When I've captured the data in XML format, I can generate different outputs
                      from one source...

                      1. The XML can be transformed into PDF, CHM, HTML formats.
                      2. The XML output can be transformed into a C/C++ stub in which API testers
                      can write their testing subroutines.
                      3. The XML output can be plugged in a customized IDE to provide Auto Sense
                      capabilities like Microsoft Visual Basic. When a user enters an object name,
                      all the attributes and properties are exposed by the IDE Auto Sense feature.

                      Typically most people are only interested in 1. But I'm interested in 1, 2,
                      and 3. Does anyone has any experience in doing 1, 2, and 3?

                      Cheers,
                      Alok


                      [Non-text portions of this message have been removed]
                    • Charles Johnston
                      Then FrameMaker is not a suitable choice, I wouldn t think. I imagine you d be giving the XML directly to those who want to use it for scenarios 2 and 3, so
                      Message 10 of 14 , Jan 3, 2006
                      • 0 Attachment
                        Then FrameMaker is not a suitable choice, I wouldn't think.

                        I imagine you'd be giving the XML directly to those who want to use it for
                        scenarios 2 and 3, so Frame isn't relevant.

                        For 1, FrameMaker wouldn't be a very good choice - Frame is great for
                        producing PDFs, but lousy at converting to HTML/CHM - you'd need yet another
                        tool (e.g. WebWorks) for HTML/CHM conversion from Frame.

                        What about Cocoon for conversion to multiple formats directly from your XML?
                        http://cocoon.apache.org/2.1/features.html

                        I'll be interested to hear how you get on...

                        Charles


                        >From: Alok Narula <tuxwarrior@...>
                        >Reply-To: xml-doc@yahoogroups.com
                        >To: xml-doc@yahoogroups.com
                        >Subject: Re: [xml-doc] Has anyone tried to integrate Doxygen
                        >OutputwithStructured Framemaker
                        >Date: Tue, 3 Jan 2006 14:38:16 +0530
                        >
                        >All:
                        >
                        >I really appreciate the knowledge and wisdom that you've shared in response
                        >to my email.
                        >
                        >The reason why I want to generate XML output from my source code is because
                        >I want to use the data captured from the source code for different
                        >consumers: API users, API testers, and Integrated Development Editors
                        >(IDE).
                        >When I've captured the data in XML format, I can generate different outputs
                        >from one source...
                        >
                        >1. The XML can be transformed into PDF, CHM, HTML formats.
                        >2. The XML output can be transformed into a C/C++ stub in which API testers
                        >can write their testing subroutines.
                        >3. The XML output can be plugged in a customized IDE to provide Auto Sense
                        >capabilities like Microsoft Visual Basic. When a user enters an object
                        >name,
                        >all the attributes and properties are exposed by the IDE Auto Sense
                        >feature.
                        >
                        >Typically most people are only interested in 1. But I'm interested in 1, 2,
                        >and 3. Does anyone has any experience in doing 1, 2, and 3?
                        >
                        >Cheers,
                        >Alok
                        >
                        >
                        >[Non-text portions of this message have been removed]
                        >
                        >
                        >
                        >
                        >Yahoo! Groups Links
                        >
                        >
                        >
                        >
                        >
                        >
                      • peterm@zeta.org.au
                        ... Charles: Ok. Armistice. Teeth settled down fine, thanks... :-) I ve had one BIG customer s rep say simply : We like to see a nice pile of paper...
                        Message 11 of 14 , Jan 4, 2006
                        • 0 Attachment
                          On Tue, 03 Jan 2006 06:50:03 +0000, Charles wrote:

                          >
                          > Help me here, I am simply wondering why "many simply don't
                          > like HTML alone". I note when you say customers "like it that
                          > way, ask for it that way, contract to have it delivered that
                          > way etc." that you didn't specifically add "need it that way".

                          Charles:

                          Ok. Armistice. Teeth settled down fine, thanks... :-)

                          I've had one BIG customer's rep say simply : "We like to see a nice pile of
                          paper..." (And they mean by that, nice print formatting....)

                          What can one say to that ? It's pretty straight forward as a doc spec...!

                          Sometimes you give up on only giving people what you think they really need,
                          and just give them what they say they want to pay for -- no matter how silly
                          it may seem. And sometimes you just don't know that they don't have other
                          people putting the requirement on them....

                          (As one instance, I might say I've actually been known to
                          provide documents with as many as 4 levels of numbered headings, for those
                          people who don't seem to understand that doc numbering has automatic updating
                          and/or why DNS was invented. But maybe their "need" was having to deal with
                          silly military specs which date back to paper-cut-and-paste days!)

                          Meanwhile, there is a good case for providing XML -- for example, for
                          customers who use XML-based content or knowledge management systems and
                          who may want to incorporate extra documents into a wider system (eg. faqs,
                          support docs, specs, management docs etc etc..) This is particularly the
                          case where tools for such systems are already designed and built around XML
                          databases and XML search engines, or maybe WSDL and various B2B operations.
                          Sure, HTML (or particularly the XHML variant of it) can be incorporated into
                          such systems, with some intermediary filtering etc. But if there's a need to
                          use specialized tags for the system, it's useful and faster to have that allowed
                          for in a locally-designed template if that is needed. And if Schemas are
                          used, handling of non-textual content may also be easier in XML.

                          In the longer term there is still the possibility or even the likelihood that
                          application-to-application conversion is going to be easier from a known XML
                          base than from HTML. Database and spreadsheet applications come to mind here..

                          If you have a mix of requirements, and have the paper-lovers as well as the KMS
                          junkies, keeping with a tool that lets you single-source does help maintain
                          sanity -- even if it means some extra intermediary steps along the way.

                          --Peter M
                        • Charles Johnston
                          Well, I conclude that no one on our side of the table thinks that API documentation in hard-copy form (and thus PDF) is really necessary, but some customers
                          Message 12 of 14 , Jan 5, 2006
                          • 0 Attachment
                            Well, I conclude that no one on our side of the table thinks that API
                            documentation in hard-copy form (and thus PDF) is really necessary, but some
                            customers want/expect/demand it, and the customer is always right (ha! ha!).
                            Anyway, who am I to criticize? I have a house full of stuff I've bought that
                            I don't need...

                            Which brings us back to the original question - is structured Frame the
                            right tool? An XML > PDF conversion through Frame would only seem justified
                            if the customer doesn't just want a PDF, but wants a very professional PDF.

                            I still believe structure is pointless if the end product is going to be
                            PDF. And I've just checked the Doxygen website, which states "There is also
                            support for generating output in RTF (MS-Word), PostScript, hyperlinked
                            PDF...". So structured Frame really does seem irrelevant.

                            Is anyone aware of other smart Doxygen > XML > PDF solutions?

                            Charles


                            >From: peterm@...
                            >Reply-To: xml-doc@yahoogroups.com
                            >To: xml-doc@yahoogroups.com
                            >Subject: Re: [xml-doc] Has anyone tried to integrate Doxygen
                            >OutputwithStructured Framemaker
                            >Date: Thu, 05 Jan 2006 12:46:43 +1100
                            >
                            >On Tue, 03 Jan 2006 06:50:03 +0000, Charles wrote:
                            >
                            > >
                            > > Help me here, I am simply wondering why "many simply don't
                            > > like HTML alone". I note when you say customers "like it that
                            > > way, ask for it that way, contract to have it delivered that
                            > > way etc." that you didn't specifically add "need it that way".
                            >
                            >Charles:
                            >
                            >Ok. Armistice. Teeth settled down fine, thanks... :-)
                            >
                            >I've had one BIG customer's rep say simply : "We like to see a nice pile
                            >of
                            >paper..." (And they mean by that, nice print formatting....)
                            >
                            >What can one say to that ? It's pretty straight forward as a doc spec...!
                            >
                            >Sometimes you give up on only giving people what you think they really
                            >need,
                            >and just give them what they say they want to pay for -- no matter how
                            >silly
                            >it may seem. And sometimes you just don't know that they don't have other
                            >people putting the requirement on them....
                            >
                            >(As one instance, I might say I've actually been known to
                            >provide documents with as many as 4 levels of numbered headings, for those
                            >people who don't seem to understand that doc numbering has automatic
                            >updating
                            >and/or why DNS was invented. But maybe their "need" was having to deal with
                            >silly military specs which date back to paper-cut-and-paste days!)
                            >
                            >Meanwhile, there is a good case for providing XML -- for example, for
                            >customers who use XML-based content or knowledge management systems and
                            >who may want to incorporate extra documents into a wider system (eg. faqs,
                            >support docs, specs, management docs etc etc..) This is particularly
                            >the
                            >case where tools for such systems are already designed and built around XML
                            >databases and XML search engines, or maybe WSDL and various B2B operations.
                            >Sure, HTML (or particularly the XHML variant of it) can be incorporated
                            >into
                            >such systems, with some intermediary filtering etc. But if there's a need
                            >to
                            >use specialized tags for the system, it's useful and faster to have that
                            >allowed
                            >for in a locally-designed template if that is needed. And if Schemas are
                            >used, handling of non-textual content may also be easier in XML.
                            >
                            >In the longer term there is still the possibility or even the likelihood
                            >that
                            >application-to-application conversion is going to be easier from a known
                            >XML
                            >base than from HTML. Database and spreadsheet applications come to mind
                            >here..
                            >
                            >If you have a mix of requirements, and have the paper-lovers as well as the
                            >KMS
                            >junkies, keeping with a tool that lets you single-source does help maintain
                            >sanity -- even if it means some extra intermediary steps along the way.
                            >
                            >--Peter M
                            >
                            >
                            >
                            >Yahoo! Groups Links
                            >
                            >
                            >
                            >
                            >
                            >
                          Your message has been successfully submitted and would be delivered to recipients shortly.