dhis2-documenters team mailing list archive

[Jason Pickering <jason.p.pickering@xxxxxxxxx>]

Hi Bob,

Again, I think the fact that docbook has moved on is to us, not so
important. We are using a very small subset of what docbook offers, and
there are no real differences between 4.4 and 5.0 for our purposes, at
least which I have seen. One issue which we should investigate more is the
supposed improved indexing in 5.0, which I have not been able to get to
work.

The major issue with upgrading the dependency from 4.4 to 4.5 of docbook
seems to be the lack of a publicly available maven artifact for either 4.4
or 5.0. We could of course build it ourselves, or try and find somewhere
where its actually available, but since I managed to get this combination
working, I never really investigated it further.

So again to emphasize, the reason we are using 4.4 is because of the tool
chain (docbkx) and getting that to work with either Docbook 4.5 or 5.0.

Regards,
Jason


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

> Jason I saw your sed script to remove comments.  That is that problem
> solved :-)
>
> I don't have any problem with the docbook toolchain and wouldn't
> lightly consider changing it.  I think it works well.  There is some
> learning involved and a shortage of non-technical tooling but yet it
> works well.  I would consider upgrading to 5.0 (or 5.1) as that might
> widen the scope of tooling available and would be relatively painless.
>
> But I agree that we need to focus on the concrete requirements rather
> than products.  And most of all, the content.
>
> On 7 April 2016 at 14:40, Jason Pickering <jason.p.pickering@xxxxxxxxx>
> wrote:
> > Perhaps, but see my earlier mail regarding framework wars.
> >
> > This is the same discussion we are having about testing, use this
> framework
> > or that framework. However, there are still too few tests, as no one can
> > agree.
> >
> > We have something which works. We have content which needs to be improved
> > and updated. If there is a compelling reason to move away from something
> > which, albeit somewhat dated ...works, maybe it would be good to outline
> the
> > reasons for this change.
> >
> >
> >
> > On Thu, Apr 7, 2016 at 10:21 PM, Knut Staring <knutst@xxxxxxxxx> wrote:
> >>
> >> 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
> >
> >
> >
> >
> > --
> > Jason P. Pickering
> > email: jason.p.pickering@xxxxxxxxx
> > tel:+46764147049
>



-- 
Jason P. Pickering
email: jason.p.pickering@xxxxxxxxx
tel:+46764147049