dhis2-documenters team mailing list archive

[Bob Jolliffe <bobjolliffe@xxxxxxxxx>]

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
>