dhis2-documenters team mailing list archive

[Bob Jolliffe <bobjolliffe@xxxxxxxxx>]

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