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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> 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 <[email protected]> >>> 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 >>> > <[email protected]> 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 <[email protected]> >>> >> 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 : [email protected] >>> >>> Unsubscribe : https://launchpad.net/~dhis2-documenters >>> >>> More help : https://help.launchpad.net/ListHelp >>> >>> >>> >> >>> >> >>> >> >>> >> -- >>> >> Jason P. Pickering >>> >> email: [email protected] >>> >> tel:+46764147049 >>> > >>> > >>> > >>> > >>> > -- >>> > Jason P. Pickering >>> > email: [email protected] >>> > tel:+46764147049 >>> > >>> > _______________________________________________ >>> > Mailing list: https://launchpad.net/~dhis2-documenters >>> > Post to : [email protected] >>> > Unsubscribe : https://launchpad.net/~dhis2-documenters >>> > More help : https://help.launchpad.net/ListHelp >>> > >>> >>> _______________________________________________ >>> Mailing list: https://launchpad.net/~dhis2-documenters >>> Post to : [email protected] >>> 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 > > _______________________________________________ Mailing list: https://launchpad.net/~dhis2-documenters Post to : [email protected] Unsubscribe : https://launchpad.net/~dhis2-documenters More help : https://help.launchpad.net/ListHelp
