On Sun, 2011-06-05 at 16:19 +0100, Bayard Bell wrote: > On 5 Jun 2011, at 15:05, Ken Gunderson wrote: > > Hello, Ken, > > > I'll let Tobias speak for himself but my read was that he has a > > preference for Sphinx but willing to use other tools. > > That was also my inference, provided we haven't hit a timeout for him to > complete the project he needs to do for his seminar. > > > I've never used > > Sphinx but took a quick look at links that Tobias posted a while back > > and it seemed like it could serve our needs pretty well. > > Nothing against Sphinx, but my immediate observation is that we're not > starting documentation from scratch. As of yet, Sphinx doesn't support > interchange from DocBook (there's a Google Code project for converting a > subset of DocBook that someone found useful), which is the source format for > the current documentation. That gives me pause. It's by no means > insurmountable, but I'd like to hear why we'd want to jump through those > hoops, with some reference to how this has worked elsewhere. I've taken a > look at a sample from the rather extensive list of projects using Sphinx, and > what I don't see so much of is large, non-Python projects like ours using it, > and that also gives me pause, which is why I've tried to do some research and > think that more research still needs to be done.
I'm less concerned with transforming from docbook to sphinx than the other direction: spninx to docbook, or sphinx to Latex, HTML, or whatever. If Tobias wants to use Sphinx AND we can transform his Sphinx output to Docbook (perhaps via Latex intermediary)... I say, turn him loose on it lest the clock run out on his project due date. > > You'd > > mentioned that your girl friend might be willing to contribute and I'd > > subsequently suggested she take Sphinx for a test drive? I'd be curious > > whether she has or not, and if so, what were her impressions? > > She's in the course of moving at the moment. Once she's settled (another week > or so), there'll be time for a test drive. > > > Iirc, Sphinx supported export to a variety of formats. Since > > documentation is something developers are historically far less keen on > > than writing code and we've got someone interested stepping up and > > contributing in this much neglected capacity, barring any technical > > reasons to the contrary, my vote would be to give Tobias the thumbs up. > > As I've explained previously, I really don't think the problem we're trying > to solve looks like that. I could just as easily say: well, there's a tool > already out there from ASF that converts existing DocBook content to > Confluence wiki (which we probably need to do in some way so that what > documentation we have is easily accessible online), there's a Confluence > plugin we can get for free that can export that back to DocBook and from > there to HTML, PDF, and man, problem solved. I'm not prepared to say that > that's the answer any more than is Sphinx, just that evaluation criteria are > different from what you suggest and the answers thus not as obvious as you > take them to be. In any case, these are decisions that are made at > #oi-meeting. > > I think we need tools that then turn into getting people involved in > documentation, this is an opportunity where we need to understand how we > capitalise on that for further opportunity. You've expressed some interest in > contributing to documentation: what would get you to become involved in this > capacity? For me the biggest barrier would be knowing what I'm talking about when it comes to OI as my Solaris experience is minimal. Hence, I might be more effective helping out on e.g. editing than actual documentation creation. At least initially. Indeed, part of my motivation for such is to learn more about said platform. I don't know Latex, but have an interest in it. I've "played" with docbook a bit a few years back but far from conversant. I would be fine with learning more about either. I need to go back and review the email Alan sent about this. While I think it's past time for OI to make a break from Oracle/Solaris, I also think we should maintain ability to leverage existing verbiage, so we should use compatible tools. -- Ken Gunderson <kgund...@teamcool.net> _______________________________________________ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
