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

RE: [xml-doc] Why use off-the-shelf tools?

Expand Messages
  • Max Dunn
    ... Yep, I ve had good luck with XSLT to MIF, as well. A bit verbose, but it works. Max
    Message 1 of 25 , Jul 22 7:38 AM
    • 0 Attachment
      > XSL:FO strikes me as a duplication of effort.
      > One can easily transform XML into Groff or TeX...

      Yep, I've had good luck with XSLT to MIF, as well. A bit verbose, but it
      works.

      Max
    • Joe Ward
      Remember, nothing is really free. All these tools--free or commercial--require setup, scripting or template development to function. 2-4 days labor cost = the
      Message 2 of 25 , Jul 22 9:55 AM
      • 0 Attachment
        Remember, nothing is really free. All these tools--free or
        commercial--require setup, scripting or template development to function.
        2-4 days labor cost = the price of the proprietary tools you mentioned, so
        if takes that much longer to get a "free" setup working, then you really
        haven't saved anything. Decide on your needs first -- then pick the most
        appropriate tools.

        Joe
      • Max Dunn
        ... In the first place, they all force you to hand code FO, there is no GUI facility to do that. Beyond that, there are unique problems with distinct
        Message 3 of 25 , Jul 22 10:44 AM
        • 0 Attachment
          >> If you ever publish to print or PDF, there can be benefits.
          >> FO is a "standard" but it's still an evolving spec (arguably
          >> a poor spec) and the implementations still generally suck.

          > Be a bit more explicit Max?
          > 'Suck' in what way?

          In the first place, they all force you to hand code FO, there is no GUI
          facility to do that. Beyond that, there are unique problems with
          distinct implementations. For example FOP is free, but "pre-alpha"
          according to Arved himself. Slow moving, the rewrite is slow-moving as
          well, did they ever get keep-with-next to work? I know the SVG support
          is worthless. RenderX is perhaps the best at formatting but is expensive
          and extremely poor performance (multiple servers required for a minimal
          volume of documents). I should look at Antenna House again, I don't know
          performance-wise but perhaps that is the best one overall (does it
          support color profiles? SVG?). But both RenderX and Antenna House have
          the problem that they are very small companies. Arbortext may come
          through with a decent implementation at some point, but they're very
          expensive, and their FO implementation still doesn't support the entire
          spec (4.3, which hasn't come out yet, won't support wrapping text around
          graphics). It's sad as well that they're adding proprietary extensions
          to make up for limitations of the spec, it would be better to get the
          spec right.

          I would really hope that a large company (i.e. Microsoft, Adobe,
          Corel...) would put a serious parallel effort into *both* the spec and
          an implementation, and it would be great if more companies would devote
          resources to FOP or some such open source project (like Sun did for
          Tomcat, IBM did for Xerces, ILOG/Sun did for Batik...). I think SVG went
          nice and quickly, while it still isn't supported by the monopoly web
          browser there is at least Batik, Illustrator, the ASV, which pretty much
          supported the 1.0 spec the day it was finalized. That is what I had
          naively hoped for with FO.

          I would like to see support for SVG as well within the FO tools. I don't
          know how far those besides FOP have gone recently towards supporting it,
          but that would be really nice.

          I don't doubt that FO is the future, it just seems to be getting here
          very slowly.

          Max
        • Paul Tremblay
          ... Agree. I wish more people got serious about contributing high-level documentation for the software. I am working on some documentation myself. But there
          Message 4 of 25 , Jul 22 11:19 AM
          • 0 Attachment
            On Mon, Jul 22, 2002 at 05:56:40PM -0700, Dave Pawson wrote:
            >
            > True. Then some people just bitch about it.
            > Others do something to help.
            >
            > DaveP.
            >

            Agree. I wish more people got serious about contributing high-level
            documentation for the software. I am working on some documentation
            myself. But there also needs to be a central place to find the
            documentation. I know about the linux documentation project, but I
            still feel strongly that the linux people (I am one of them) take the
            task of writing the software seriously, but do not take take the
            task of documentation at all seriously.

            For example, I am writing a script to convert rtf to xml. I am
            writing it in perl. There is a module for tagging the rtf already
            avalible in perl, but the documentation that accompanies it is 2
            lines long. I couldn't figure out how to use it, so I didn't. I've
            said this on several mailing lists: good software without
            documentation is like a mercedes without a steering wheel.

            I wonder if a lot of people get turned away from free software for
            this reason?

            I know I'm belabouring this point, but I don't think many of the
            free software advocates realize how frustrating figuring out how to use
            something can be. When you try to bring up this point, they get very
            defensive, so no serious effort is made to change things.

            Paul

            --

            ************************
            *Paul Tremblay *
            *phthenry@...*
            ************************
          • Max Dunn
            ... What FO tool do you use/like? Does it persist vectors in PDF? If so from what format(s)? Thanks, Max
            Message 5 of 25 , Jul 22 11:26 AM
            • 0 Attachment
              > So far, I'm happy with images in pdf output.

              What FO tool do you use/like? Does it persist vectors in PDF? If so from
              what format(s)?

              Thanks,

              Max
            • sara.mitchell@ps.ge.com
              To some extent (although less so in software that costs), this is true everywhere :-/ [snipped from Paul Tremblay] ... Thanks! I will have to remember this
              Message 6 of 25 , Jul 22 11:49 AM
              • 0 Attachment
                To some extent (although less so in software that costs),
                this is true everywhere :-/

                [snipped from Paul Tremblay]
                > I know about the linux documentation project, but I
                > still feel strongly that the linux people (I am one of them) take the
                > task of writing the software seriously, but do not take take the
                > task of documentation at all seriously.

                Thanks! I will have to remember this quote that next time
                I have to argue with management about why they shouldn't
                skip the documentation :-)

                >I've
                > said this on several mailing lists: good software without
                > documentation is like a mercedes without a steering wheel.
                >

                And I would personally say that this one is true, especially
                for non-programmer types like me:

                > I wonder if a lot of people get turned away from free software for
                > this reason?

                A question (because I don't work in open-source, at least not
                at the moment) that I always have is whether companies are
                supporting open-source programmers to some degree? If that's true,
                do they also consider supporting technical writers to get
                the documentation done? Or is this another place where they just
                don't think about documentation?

                >
                > I know I'm belabouring this point, but I don't think many of the
                > free software advocates realize how frustrating figuring out
                > how to use
                > something can be. When you try to bring up this point, they get very
                > defensive, so no serious effort is made to change things.

                Well, if the programmers have to do all the documentation themselves,
                which sounds likely, then this reponse is not surprising. Not to
                denegrate anyone on the list, but my personal experience is that
                about 75% of programmers don't like to write documentation,
                and even the 25% who feel obligated frequently don't feel comfortable
                writing for audiences that are not at their level. It's ususally the
                last thing programmers want to do (and therefore very easy to put off).
                This is why they *need* technical writers ;-)

                Sara
              • larry.kollar@arrisi.com
                ... function. ... Half right... well, completely right for the special case of a department of one. But for larger groups, you can propagate a completed setup
                Message 7 of 25 , Jul 22 11:51 AM
                • 0 Attachment
                  Joe Ward wrote:

                  > Remember, nothing is really free. All these tools--free or
                  > commercial--require setup, scripting or template development to
                  function.
                  > 2-4 days labor cost = the price of the proprietary tools you mentioned, so
                  > if takes that much longer to get a "free" setup working, then you really
                  > haven't saved anything.

                  Half right... well, completely right for the special case of
                  a department of one. But for larger groups, you can propagate
                  a completed setup to as many seats as necessary in a few
                  minutes. The larger the group, the lower the cost per seat of
                  the setup -- while the cost per seat of the core software
                  doesn't change (until you hit site-licensing volumes). Using
                  free software, the cost per seat savings add up pretty quickly.

                  The perceived cost advantage for most commercial software comes
                  from lower skill levels required to make Something Happen. The
                  savings are obvious (lower salaries), the costs are not (lower
                  productivity, lower quality, downtime when something goes wrong
                  and nobody knows how to fix it).


                  > Decide on your needs first -- then pick the most
                  > appropriate tools.

                  No argument there, but remember to take all factors into
                  account when deciding what's appropriate. There are a lot
                  of hidden costs to the easy way that you may not find until
                  it's far too late. I could go all afternoon about that,
                  but I'll spare you. This time. :-)

                  --
                  Larry Kollar, Senior Technical Writer, ARRIS
                  "Content creators are the engine that drives
                  value in the information life cycle."
                  -- Barry Schaeffer, on XML-Doc
                • Max Dunn
                  ... Depends what parser you re using. :-) What I mean is, say you have a nice SVG graphic that defines a path. You can, of course, with say ASV or Batik, zoom
                  Message 8 of 25 , Jul 22 11:56 AM
                  • 0 Attachment
                    > 'Persist vectors in PDF'? Doesn't parse Max.

                    Depends what parser you're using. :-)

                    What I mean is, say you have a nice SVG graphic that defines a path. You
                    can, of course, with say ASV or Batik, zoom in and out and see that path
                    and it will still be smooth because it's defined as a vector. Same goes
                    for a typical EPS file. However, some of the tools that create PDF
                    *rasterize* the output (for example FrameMaker does this with SVG, but
                    not with EPS). Then when you zoom in on the PDF, you see jagged steps
                    instead of the smooth paths... it can also radically increase file size.

                    Max
                  • Paul Tremblay
                    ... Amen. This is very well put. I also don t want to offend programmers, but my feeling is that their strength is in programming, and not technical writing.
                    Message 9 of 25 , Jul 22 12:47 PM
                    • 0 Attachment
                      On Mon, Jul 22, 2002 at 02:49:19PM -0400, sara.mitchell@... wrote:
                      >
                      > Well, if the programmers have to do all the documentation themselves,
                      > which sounds likely, then this reponse is not surprising. Not to
                      > denegrate anyone on the list, but my personal experience is that
                      > about 75% of programmers don't like to write documentation,
                      > and even the 25% who feel obligated frequently don't feel comfortable
                      > writing for audiences that are not at their level. It's ususally the
                      > last thing programmers want to do (and therefore very easy to put off).
                      > This is why they *need* technical writers ;-)
                      >

                      Amen. This is very well put. I also don't want to offend programmers, but
                      my feeling is that their strength is in programming, and not technical
                      writing. Hence, much of the documentation is filled with jargon and
                      assumes the user has knowledge that he/she doesn't.

                      Anyway, I don't want to denigrate free software. I am hoping increase
                      the quality of the docs.

                      Paul

                      --

                      ************************
                      *Paul Tremblay *
                      *phthenry@...*
                      ************************
                    • larry.kollar@arrisi.com
                      ... The whole anarchic nature of Linux (and free software) development more or less precludes the existence of a central place for documentation. I think
                      Message 10 of 25 , Jul 22 1:28 PM
                      • 0 Attachment
                        Paul Tremblay wrote:

                        > ... there also needs to be a central place to find the
                        > documentation. I know about the linux documentation project, but I
                        > still feel strongly that the linux people (I am one of them) take the
                        > task of writing the software seriously, but do not take take the
                        > task of documentation at all seriously.

                        The whole anarchic nature of Linux (and free software) development
                        more or less precludes the existence of a "central place" for
                        documentation. I think tldp.org is going to be as close as it gets,
                        and it can't (and shouldn't) necessarily link to everything. For
                        example, I just installed Debian (woody) on an old laptop, and I
                        found plenty of info to help me get it done -- none of it on tldp.

                        Part of the problem, IMO, is a perceived lack of documentation
                        tools. While SGML was designed for hand-coding, all of the
                        minimization options were ripped out for XML. There are several
                        workarounds -- LyX and AbiWord[1] can output a subset of DocBook,
                        TLDP has a Wiki-like markup language[2] with a DocBook transform
                        script, and I suppose you could use sgmlnorm to turn hand-coded
                        SGML into XML -- but if someone released a free tool that could
                        edit DocBook directly & had a comfortable GUI, it would have no
                        lack of users.

                        [1] AbiWord is also supposed to do a great job exporting to
                        XHTML, but I haven't tried it personally. I have AW on three
                        computers at home, so I'll check it out eventually.

                        [2] I'd like to see TLDP drop the "-like" and open up a full-
                        blown Wiki for at least the initial draft(s) of new documents.
                        But despite the track record of people not doing nasty things
                        on wide-open Wikis, the leaders are reluctant to take that step.
                        Bummer.


                        > I've said this on several mailing lists: good software without
                        > documentation is like a mercedes without a steering wheel.

                        Coming soon to a .signature near you, I'm sure. :-)


                        > I wonder if a lot of people get turned away from free software for
                        > this reason?

                        Possibly. There's a humorous look at the "Top 10 Dumbest Things
                        Linux Users Say" at
                        http://www.tuxreports.com/modules.php?op=modload&name=News&file=article&sid=892&mode=thread&order=0&thold=0
                        (beware the line wrap beast)
                        This thread is about the third mention of documentation I've seen
                        in the last week or so -- perhaps a critical mass is forming and
                        we'll soon start seeing the community start taking documentation
                        seriously. We can always hope....

                        --
                        Larry Kollar, Senior Technical Writer, ARRIS
                        "Content creators are the engine that drives
                        value in the information life cycle."
                        -- Barry Schaeffer, on XML-Doc
                      • Dave Pawson
                        ... Be a bit more explicit Max? Suck in what way? DaveP
                        Message 11 of 25 , Jul 22 5:47 PM
                        • 0 Attachment
                          At 13:00 21/07/2002, Max Dunn wrote:
                          >> What are the benefits of buying expensive proprietray
                          >> tools that do not fully support xml yet?
                          >
                          >If you ever publish to print or PDF, there can be benefits. FO is a
                          >"standard" but it's still an evolving spec (arguably a poor spec) and
                          >the implementations still generally suck.


                          Be a bit more explicit Max?

                          'Suck' in what way?

                          DaveP
                        • Dave Pawson
                          ... True. Then some people just bitch about it. Others do something to help. DaveP.
                          Message 12 of 25 , Jul 22 5:56 PM
                          • 0 Attachment
                            At 21:45 21/07/2002, Paul Tremblay wrote:


                            >I've just re-posted the part of your message I find most interesting.
                            >You are exactly right to say that free tools lack good documentation. I
                            >use free tools myself, and am absolutely frustrated by the lack of good
                            >documentation. The people in the free-use community spend a hell of a
                            >lot of time writing good software, but then make it unaccesible by the
                            >lack of documentation.

                            True. Then some people just bitch about it.
                            Others do something to help.

                            DaveP.
                          • Dave Pawson
                            ... True, but its not (IMO) intended for handcrafting. Remember its bg as part of XSL? ... Not yet. ... Off topic. ... For server side (ala XSLT) yep. That s
                            Message 13 of 25 , Jul 22 7:11 PM
                            • 0 Attachment
                              At 10:44 22/07/2002, Max Dunn wrote:

                              >In the first place, they all force you to hand code FO, there is no GUI
                              >facility to do that.

                              True, but its not (IMO) intended for handcrafting. Remember its bg
                              as part of XSL?

                              > Beyond that, there are unique problems with
                              >distinct implementations. For example FOP is free, but "pre-alpha"
                              >according to Arved himself. Slow moving, the rewrite is slow-moving as
                              >well, did they ever get keep-with-next to work?

                              Not yet.

                              > I know the SVG support
                              >is worthless.

                              Off topic.

                              > RenderX is perhaps the best at formatting but is expensive
                              >and extremely poor performance (multiple servers required for a minimal
                              >volume of documents).

                              For server side (ala XSLT) yep. That's usage.

                              > I should look at Antenna House again, I don't know
                              >performance-wise but perhaps that is the best one overall (does it
                              >support color profiles? SVG?).

                              Nope, nope (nor need it)

                              > But both RenderX and Antenna House have
                              >the problem that they are very small companies.

                              Small = problem? Do you still buy all your kit from IBM?

                              > Arbortext may come
                              >through with a decent implementation at some point, but they're very
                              >expensive, and their FO implementation still doesn't support the entire
                              >spec (4.3, which hasn't come out yet, won't support wrapping text around
                              >graphics).

                              Probably because its not in the XSL-FO spec.

                              > It's sad as well that they're adding proprietary extensions
                              >to make up for limitations of the spec, it would be better to get the
                              >spec right.

                              Probably at user demand?


                              >I would really hope that a large company (i.e. Microsoft, Adobe,
                              >Corel...) would put a serious parallel effort into *both* the spec and
                              >an implementation, and it would be great if more companies would devote
                              >resources to FOP or some such open source project (like Sun did for
                              >Tomcat, IBM did for Xerces, ILOG/Sun did for Batik...). I think SVG went
                              >nice and quickly, while it still isn't supported by the monopoly web
                              >browser there is at least Batik, Illustrator, the ASV, which pretty much
                              >supported the 1.0 spec the day it was finalized. That is what I had
                              >naively hoped for with FO.

                              Even more niche than SVG?


                              >I would like to see support for SVG as well within the FO tools.

                              So far, I'm happy with images in pdf output.

                              Regards DaveP.
                            • Dave Pawson
                              ... History? Get that software out the door mandates don t help :-) The boss doesn t get paid for delivering documentation. ... yawc? ... Yep. It was my
                              Message 14 of 25 , Jul 22 7:23 PM
                              • 0 Attachment
                                At 11:19 22/07/2002, Paul Tremblay wrote:

                                >Agree. I wish more people got serious about contributing high-level
                                >documentation for the software. I am working on some documentation
                                >myself. But there also needs to be a central place to find the
                                >documentation. I know about the linux documentation project, but I
                                >still feel strongly that the linux people (I am one of them) take the
                                >task of writing the software seriously, but do not take take the
                                >task of documentation at all seriously.

                                History? Get that software out the door mandates don't help :-)
                                The boss doesn't get paid for delivering documentation.


                                >For example, I am writing a script to convert rtf to xml.

                                yawc?

                                >I wonder if a lot of people get turned away from free software for
                                >this reason?

                                Yep. It was my motivation for writing a book :-)
                                SGML+dsssl+emacs all at one go kept me struggling for a year.


                                >I know I'm belabouring this point, but I don't think many of the
                                >free software advocates realize how frustrating figuring out how to use
                                >something can be.

                                No, they don't need it. They wrote the code!

                                > When you try to bring up this point, they get very
                                >defensive, so no serious effort is made to change things.

                                Its (somehow) a different group of people.
                                And its hard to attract them.
                                All the glory goes to the designers, not the documenters,
                                probably with a few exceptions. Markus Hoenika (I wish I could
                                spell/remember how to spell his name properly).

                                Regards DaveP.
                              • Dave Pawson
                                ... Renderx and Antenna House. Latter for quick tests, both to check a spec point. I should be using PassiveTex as well but a re-install of win2K is lacking
                                Message 15 of 25 , Jul 22 7:29 PM
                                • 0 Attachment
                                  At 11:26 22/07/2002, you wrote:
                                  >> So far, I'm happy with images in pdf output.
                                  >
                                  >What FO tool do you use/like? Does it persist vectors in PDF? If so from
                                  >what format(s)?

                                  Renderx and Antenna House. Latter for quick tests, both to check
                                  a spec point.
                                  I should be using PassiveTex as well but a re-install of win2K is
                                  lacking texLive 6 (I think 7 is available for download now).

                                  'Persist vectors in PDF'? Doesn't parse Max.

                                  regards DaveP
                                • Dave Pawson
                                  ... Good question. I d be intrigued to see some quotes when this is asked! That would make good reading. ... The only group I know of that has a sparse support
                                  Message 16 of 25 , Jul 23 6:42 AM
                                  • 0 Attachment
                                    At 11:49 22/07/2002, you wrote:

                                    >A question (because I don't work in open-source, at least not
                                    >at the moment) that I always have is whether companies are
                                    >supporting open-source programmers to some degree? If that's true,
                                    >do they also consider supporting technical writers to get
                                    >the documentation done? Or is this another place where they just
                                    >don't think about documentation?

                                    Good question. I'd be intrigued to see some quotes when this
                                    is asked! That would make good reading.


                                    >Well, if the programmers have to do all the documentation themselves,
                                    >which sounds likely, then this reponse is not surprising. Not to
                                    >denegrate anyone on the list, but my personal experience is that
                                    >about 75% of programmers don't like to write documentation,
                                    >and even the 25% who feel obligated frequently don't feel comfortable
                                    >writing for audiences that are not at their level. It's ususally the
                                    >last thing programmers want to do (and therefore very easy to put off).
                                    >This is why they *need* technical writers ;-)

                                    The only group I know of that has a sparse support of tech writers
                                    (in output if not in name) is the x86 group which has a list concerned
                                    with the documentation, not the product.

                                    Regards DaveP
                                  • Dave Pawson
                                    ... I did and wasn t impressed. Staroffice 6 is much closer to the mark. Sourceforge has a *office to docbook project. Regards DaveP
                                    Message 17 of 25 , Jul 23 6:48 AM
                                    • 0 Attachment
                                      At 13:28 22/07/2002, you wrote:


                                      >[1] AbiWord is also supposed to do a great job exporting to
                                      >XHTML, but I haven't tried it personally. I have AW on three
                                      >computers at home, so I'll check it out eventually.

                                      I did and wasn't impressed. Staroffice 6 is much closer
                                      to the mark. Sourceforge has a *office to docbook project.

                                      Regards DaveP
                                    • Paul Tremblay
                                      ... I just checked out yawc, and notice it is only compatible with Windows. Or am I wrong? How good a job does the yawc light version do? Their website states
                                      Message 18 of 25 , Jul 23 9:32 PM
                                      • 0 Attachment
                                        >
                                        >
                                        > >For example, I am writing a script to convert rtf to xml.
                                        >
                                        > yawc?
                                        >

                                        I just checked out yawc, and notice it is only compatible with Windows.
                                        Or am I wrong? How good a job does the yawc light version do?

                                        Their website states that you have to have Word 97 or higher. But surely
                                        it could convert earlier, simpler versions of RTF?

                                        Paul

                                        --

                                        ************************
                                        *Paul Tremblay *
                                        *phthenry@...*
                                        ************************
                                      • Dave Pawson
                                        ... I can t speak from experience of yawc, my comment was slightly tounge in cheek, since there must be about a dozen such products out there now, some os,
                                        Message 19 of 25 , Jul 24 6:44 PM
                                        • 0 Attachment
                                          At 21:32 23/07/2002, you wrote:

                                          >I just checked out yawc, and notice it is only compatible with Windows.
                                          >Or am I wrong? How good a job does the yawc light version do?
                                          >
                                          >Their website states that you have to have Word 97 or higher. But surely
                                          >it could convert earlier, simpler versions of RTF?

                                          I can't speak from experience of yawc, my comment was slightly tounge
                                          in cheek, since there must be about a dozen such products out there now,
                                          some os, some commercial.

                                          A google search should reveal many of them.

                                          Sorry to confuse.

                                          Regards DaveP.
                                        Your message has been successfully submitted and would be delivered to recipients shortly.