dhis2-documenters team mailing list archive

[Knut Staring <knutst@xxxxxxxxx>]

I see that Flare supports DITA, would that be a good alternative to DocBook?

http://dita.xml.org/

On Thu, Apr 7, 2016 at 3:16 PM, Bob Jolliffe <bobjolliffe@xxxxxxxxx> wrote:

> On a spectrum between low-level standardized technical docbook through
> to "user friendly" (use Word), vendor-locked proprietary and patent
> encumbered technology, this one seems to fall on the far right :-)
> Not quite what I had in mind.
>
> I can see the attraction but I would be very wary to go in this direction.
>
> On 7 April 2016 at 13:52, Rachael Brooke <rachael@xxxxxxxxx> wrote:
> > Hi everyone,
> >
> > Cecilia and I have been thinking about trying out a new tool that could
> > handle big documentation projects, translation files and other
> resources. So
> > it's good timing that this issue is being raised by you.
> >
> > We were considering looking into a solution which you may know, called
> > MadCap Flare: http://www.madcapsoftware.com/products/flare/.
> >
> > If you have any other suggestions, we'd be happy to hear your thoughts.
> >
> > Thanks for bringing this up - we're investigating!
> >
> > Rachael
> >
> > On Thu, Apr 7, 2016 at 1:42 PM, Knut Staring <knutst@xxxxxxxxx> wrote:
> >>
> >> Would be good to hear from our new documentation experts (Rachael and
> >> Cecilia) on this issue (what kinds of tools they would be comfortable
> with
> >> etc).
> >>
> >> Knut
> >>
> >> On Thu, Apr 7, 2016 at 1:30 PM, Bob Jolliffe <bobjolliffe@xxxxxxxxx>
> >> wrote:
> >>>
> >>> Hi Jason, Lars
> >>>
> >>> I am not sure the link about oxygen nested comments is really
> >>> addressing the "thing".
> >>>
> >>> I agree with Lars that having the "<!-- Created by Serna Free -->"
> >>> text inserted into all our documents is ugly, wrong and misleading.
> >>> If you are using Serna Free I think it might be a simple courtesy to
> >>> just strip those comments before committing.  Of course its possible
> >>> to forget and maybe some sort of removal hook could be configured
> >>> automatically (sed, xsltproc ..) but its maybe not so hard to just
> >>> delete the line.
> >>>
> >>> I am not sure of what the problem is with oxygen encountering these
> >>> comments are though.  Maybe I also don't get the "thing" :-)  I open
> >>> the docbook files with oxygen and don't encounter a problem related to
> >>> the comment.  The docbook4 "type" seems to be immediately recognized
> >>> and I get a Docbook4 menu appear when I switch to author mode whether
> >>> the comment is there or not.  Is it an oxygen version issue (I
> >>> currently use 17.1) or is there some other issue I am missing?
> >>>
> >>> Though I think there are deeper issues at play.  First is that Serna
> >>> Free seems no longer to be maintained (as a free version).  One
> >>> consequence of this being that using it keeps us frozen in time at
> >>> docbook 4.4.  The last release of the docbook 4.x series was 4.5 back
> >>> in 2006.  The 5.0 (and now 5.1) series has been out for quite a long
> >>> time now (2009?).  AFAIK the only reason for sticking with 4.x has
> >>> been the availability of Serna Free.
> >>>
> >>> (Which is not a small thing.  The sad truth is that  another good free
> >>> candidate for docbook editing by non-technical authors hasn't ever
> >>> emerged.  Of course if you are more than a bit geeky then emacs does a
> >>> good job.  But even I don't use emacs anymore for editing docbook
> >>> documents.  I use oxygen, which is not free.)
> >>>
> >>> Two thoughts come to mind:
> >>> (i) it probably really makes sense to rejoin the (docbook) world and
> >>> move from 4.4 to 5.0.  Particularly if the now defunct Serna Free is
> >>> the only factor holding us back.  I understand that there are
> >>> transforms available to make this a painless journey.  The best
> >>> available in terms of free editing tools with a strong docbook focus
> >>> seems to be the eclipse DEP4E plugin.  Otherwise there are the
> >>> non-free tools as well as host of xml schema aware editors.
> >>> Admittedly none of these really qualify as eminently suitable for
> >>> non-technical authors so the problem isn't really completely solved,
> >>> but maybe improved slightly.
> >>>
> >>> (ii) more radically, it might be time to consider moving from docbook
> >>> altogether.  There are a host of "cool" alternatives (markdown and
> >>> friends) none of which I am fond of, but they have enthusiastic
> >>> supporters.  To me they all seem like endless reinventions of
> >>> roff/nroff/groff and certainly lack the maturity of docbook.   But
> >>> maybe the world has moved to a stage that its possible to consider
> >>> editing html5/css3 documents directly?  Certainly there is
> >>> considerable user friendly editing tools available.  And conversion to
> >>> pdf seems not to be a problem.  Though whether this would cause the
> >>> clean structure of documents to descend into anarchy I don't really
> >>> know.
> >>>
> >>> My 2 cents.  I would certainly advocate (i) above (though admit its a
> >>> strong response to just getting rid of Serna Free comments).  (ii)
> >>> frightens me quite a bit. Certainly would be a lot of work.
> >>>
> >>> In the end comes down to (i) who will do most of the documentation and
> >>> what do they like or tolerate, (ii) what effort is justified to fiddle
> >>> with what is really quite a nice looking set of existing
> >>> documentation.
> >>>
> >>> For the moment lets at least agree to keep those horrible comments out.
> >>>
> >>> Bob
> >>>
> >>> On 6 April 2016 at 11:31, Jason Pickering <jason.p.pickering@xxxxxxxxx
> >
> >>> wrote:
> >>> > For instance, perhaps this
> >>> >
> >>> > http://www.oxygenxml.com/forum/topic3658.html
> >>> >
> >>> > which seems to describe a means of getting around comments.
> >>> >
> >>> >
> >>> >
> >>> > On Wed, Apr 6, 2016 at 7:01 PM, Jason Pickering
> >>> > <jason.p.pickering@xxxxxxxxx> wrote:
> >>> >>
> >>> >> Hi Lars,
> >>> >> I think there must be a way around this, and I would not be in favor
> >>> >> at
> >>> >> all of ditching Serna. Its a good tool and not everyone has access
> to
> >>> >> a
> >>> >> relatively expensive commercial tool like Oxygen.
> >>> >>
> >>> >> Serna Free inserts this automatically unfortunately when it saves
> the
> >>> >> document, but lets look for a look around to deal with this in
> Oxygen.
> >>> >>
> >>> >> Regards,
> >>> >> Jason
> >>> >>
> >>> >>
> >>> >> On Wed, Apr 6, 2016 at 6:44 PM, Lars Helge Øverland <lars@xxxxxxxxx
> >
> >>> >> wrote:
> >>> >>>
> >>> >>> Hi,
> >>> >>>
> >>> >>> re the documentation.The Serna editor horribly inserts a
> >>> >>>
> >>> >>> <!-- Created by Serna Free -->
> >>> >>>
> >>> >>> comment in all files it creates before the DTD. This throws off
> >>> >>> Oxygen
> >>> >>> from detecting it to be a Docbook format. Lets not use Serna
> anymore
> >>> >>> or at
> >>> >>> least make sure we don't get comments in the beginning of docbook
> xml
> >>> >>> files.
> >>> >>>
> >>> >>> Lars
> >>> >>>
> >>> >>> --
> >>> >>> Lars Helge Øverland
> >>> >>> Lead developer, DHIS 2
> >>> >>> University of Oslo
> >>> >>> Skype: larshelgeoverland
> >>> >>> http://www.dhis2.org
> >>> >>>
> >>> >>>
> >>> >>> _______________________________________________
> >>> >>> Mailing list: https://launchpad.net/~dhis2-documenters
> >>> >>> Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> >>> Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> >>> More help   : https://help.launchpad.net/ListHelp
> >>> >>>
> >>> >>
> >>> >>
> >>> >>
> >>> >> --
> >>> >> Jason P. Pickering
> >>> >> email: jason.p.pickering@xxxxxxxxx
> >>> >> tel:+46764147049
> >>> >
> >>> >
> >>> >
> >>> >
> >>> > --
> >>> > Jason P. Pickering
> >>> > email: jason.p.pickering@xxxxxxxxx
> >>> > tel:+46764147049
> >>> >
> >>> > _______________________________________________
> >>> > Mailing list: https://launchpad.net/~dhis2-documenters
> >>> > Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> > Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> > More help   : https://help.launchpad.net/ListHelp
> >>> >
> >>>
> >>> _______________________________________________
> >>> Mailing list: https://launchpad.net/~dhis2-documenters
> >>> Post to     : dhis2-documenters@xxxxxxxxxxxxxxxxxxx
> >>> Unsubscribe : https://launchpad.net/~dhis2-documenters
> >>> More help   : https://help.launchpad.net/ListHelp
> >>
> >>
> >>
> >>
> >> --
> >> Knut Staring
> >> Dept. of Informatics, University of Oslo
> >> Norway: +4791880522
> >> Skype: knutstar
> >> http://dhis2.org
> >
> >
>



-- 
Knut Staring
Dept. of Informatics, University of Oslo
Norway: +4791880522
Skype: knutstar
http://dhis2.org