dhis2-documenters team mailing list archive

[Bob Jolliffe <bobjolliffe@xxxxxxxxx>]

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
>
>