Subject: Re: [OMPI docs] Docs suggestions
From: Shao-Ching Huang (huangsc_at_[hidden])
Date: 2013-10-10 13:07:57
Hi Kel,
Thanks for organizing this. Please send the repo's URL when it is ready to
accept pull requests.
Regards,
Shao-Ching
On Thu, Oct 10, 2013 at 6:07 AM, Kelly Black <kjblack_at_[hidden]> wrote:
> Dear Shao-Ching,
>
> Sorry for the delay in responding to this. I took some time play around
> with sphinx and try some things with it. It is very easy to set up, and the
> mark up language is easy to use. There are a few unhappy quirks, but
> overall I kind of like it. It makes it easy to create large html documents
> with cross referenced links.
>
> I made a new branch, sphinx, in the Open MPI document repo and have
> converted the first two latex files over to rst format. It was a bit clumsy
> at first as I learned some of the details, but I am happy with the results.
>
> I would like to just keep moving forward and use this to generate the html.
>
> Sincerely,
> Kel
>
> _______________________________________________________
> Kelly Black Phone: (315) 600-8334
> Clarkson University Fax: (315) 268-2371
> Department of Math. & C.S.
> PO Box 5815
> Potsdam, NY 13699-5815
> USA
>
>
> On Thu, Sep 26, 2013 at 3:46 PM, Shao-Ching Huang <huangsc_at_[hidden]>wrote:
>
>> Like many other systems, the conveniences of using Sphinx also come
>> with all the baggage it carries. It uses a certain template system. It
>> comes with a few certain default layouts ("themes",
>> http://sphinx-doc.org/theming.html). Many things are configurable, but
>> one will have to manipulate within Sphinx's framework.
>>
>> My experiences with Sphinx are that if the what you want is close to
>> one of the default layouts, then things are really easy, time-saving
>> and smooth -- it allows you to totally focus on content texts in clean
>> plain texts and get good-looking "for free". On the other hand, if you
>> want a dramatically different layout, some hacking may be required.
>>
>> Another possibility is just write in LaTeX (which seems to be the
>> original plan). If there are concerns about latex2html, how about
>> tex4ht (http://tug.org/applications/tex4ht/mn.html) which seems much
>> more flexible in controlling the HTML output? Any comments on this?
>>
>> My sense is there is no one source format that will satisfy all
>> requirements. At some point, we will have to just pick up a reasonable
>> format and just start using it. Say, a few months into the project, if
>> the choice turns out to be really bad, it is not impossible to switch
>> with the help of some tools.
>>
>> Shao-Ching
>>
>> On Thu, Sep 26, 2013 at 11:26 AM, Kelly Black <kjblack_at_[hidden]> wrote:
>> > Hello,
>> >
>> > I just took a quick look at the documentation on Sphinx at their
>> website.
>> > My first reaction is that it did not seem like something that would eat
>> my
>> > cats and lay waste to the surrounding town. It seems to have the
>> facilities
>> > to create a well structured system of documents, and the markeup
>> appears to
>> > be relatively straight forward. Is there anything really wrong with it?
>> >
>> > Besides if we judged HTML by the documents some people create with it we
>> > would have banned it a long time ago.
>> >
>> > Sincerely,
>> > Kel
>> >
>> > _______________________________________________________
>> > Kelly Black Phone: (315) 600-8334
>> > Clarkson University Fax: (315) 268-2371
>> > Department of Math. & C.S.
>> > PO Box 5815
>> > Potsdam, NY 13699-5815
>> > USA
>> >
>> >
>> > On Tue, Sep 24, 2013 at 8:38 PM, Shao-Ching Huang <huangsc_at_[hidden]>
>> wrote:
>> >>
>> >> There are some projects using sphinx:
>> >> http://docs.openstack.org/developer/swift/
>> >> http://fenicsproject.org/
>> >> http://ipython.org/
>> >>
>> >> Authors write plain text that looks like this (without the HTML tags
>> >> explicitly):
>> >>
>> >>
>> https://bitbucket.org/fenics-project/fenics-web/raw/262ac46e900d3ed81fb01e7c8efb050be9c70d9b/source/documentation/tutorial/materials.rst
>> >>
>> >> One useful feature of a system like Sphinx is, like latex, it can
>> >> automatically generates links and indices across source files.
>> >>
>> >> IMHO, there is probably no perfect solution in choosing a source
>> >> format. If the OpenMPI docs project is to be a collaborative effort,
>> >> it may be useful to pick a format/system that is easy to
>> >> write/contribute/maintain among OpenMPI users (I suppose many of them
>> >> are computational/application scientists who may have deep knowledge
>> >> in MPI/OpenMPI but not necessarily so in web site rendering).
>> >> Something can can support a document consisting of multiple chapters
>> >> (think latex "book" class), can easily output (reasonably modern-look)
>> >> HTML for web viewing, can generate a PDF for offline reading,
>> >> somewhat-"easy"-to-write source format, in plain text files (version
>> >> control), automatic index/cross-link (think latex "label") generation,
>> >> would be a good candidate.
>> >>
>> >> Thanks,
>> >>
>> >> Shao-Ching
>> >>
>> >>
>> >> On Tue, Sep 24, 2013 at 2:47 PM, Kelly Black <kjblack_at_[hidden]>
>> wrote:
>> >> > Hello,
>> >> >
>> >> > If you want output in HTML then just using HTML is a good choice. It
>> >> > would
>> >> > be relatively straightforward to use a template system to make it
>> easier
>> >> > to
>> >> > maintain and ensure uniformity over multiple pages with options for
>> >> > different page lengths. Working in HTML is relatively straight
>> forward
>> >> > and
>> >> > there are multiple choices with respect to authoring tools to appeal
>> to
>> >> > more
>> >> > people.
>> >> >
>> >> > It is a good idea to make the Open MPI aspects the primary material
>> for
>> >> > the
>> >> > document. I think it is important to have the simple examples and
>> broad
>> >> > overview of MPI programming. I recently came back to MPI after a long
>> >> > hiatus, and I found it difficult to find good material to get
>> started. I
>> >> > ended up having to collect material from a wide variety of sources
>> which
>> >> > was
>> >> > frustrating.
>> >> >
>> >> > -Kel
>> >> >
>> >> > _______________________________________________________
>> >> > Kelly Black Phone: (315) 600-8334
>> >> > Clarkson University Fax: (315) 268-2371
>> >> > Department of Math. & C.S.
>> >> > PO Box 5815
>> >> > Potsdam, NY 13699-5815
>> >> > USA
>> >> >
>> >> >
>> >> > On Tue, Sep 24, 2013 at 2:42 PM, <manday_at_[hidden]> wrote:
>> >> >>
>> >> >> Sphinx is one of the most awful and dysfunctional documentation
>> systems
>> >> >> that I've ever seen. Admitted, I only had to deal with it in the
>> >> >> context
>> >> >> of Python and associates, but that was enough to seriously
>> traumatize
>> >> >> me.
>> >> >>
>> >> >> Considering documentation, your primary concern should be that of
>> >> >> finding a powerful and yet easy-to-write markup language.
>> Presentation
>> >> >> is a subordinate matter - tools like pandoc will eventually always
>> >> >> allow
>> >> >> you to render any kind of presentation you prefer.
>> >> >>
>> >> >> In my opinion, HTML and EPUB are the best things we have for writing
>> >> >> technical documents at the moment. EPUB still suffers from not being
>> >> >> able to display mathematical contents, but that should be of little
>> >> >> meaning for OpenMPI. HTML5 on the other hand, is a bit lacking with
>> >> >> regard to defining meta data.
>> >> >>
>> >> >> Writing HTML isn't that bad. It may be not as convenient as writing
>> >> >> TeX,
>> >> >> but it offers the considerable advantage of being a clearly
>> structured
>> >> >> and readily available markup language.
>> >> >>
>> >> >> I've had only good experiences writing documents in HTML5, so if I
>> were
>> >> >> to give a vote, I'd opt for HTML.
>> >> >>
>> >> >> On Tue, Sep 24, 2013 at 09:53:06AM -0700, Shao-Ching Huang wrote:
>> >> >> > Hi,
>> >> >> >
>> >> >> > Regarding the source format, if LaTeX is out of the table, may I
>> >> >> > suggest Sphinx, http://sphinx-doc.org/. Sphinx can generate
>> outputs
>> >> >> > in
>> >> >> > HTML, latex, texinfo, pdf, etc. formats. The source is mostly
>> >> >> > reStructuredText, so like asciidoc and markdown, it is less burden
>> >> >> > for
>> >> >> > writers. Embedded code examples can be highlighted by pygment
>> >> >> > (http://pygments.org/).
>> >> >> >
>> >> >> > Shao-Ching Huang
>> >> >> >
>> >> >> >
>> >> >> > On Tue, Sep 24, 2013 at 9:07 AM, Jeff Squyres (jsquyres)
>> >> >> > <jsquyres_at_[hidden]> wrote:
>> >> >> > > On the weekly Open MPI engineering call today, we talked about
>> the
>> >> >> > > docs project.
>> >> >> > >
>> >> >> > > The developer community had a few suggestions:
>> >> >> > >
>> >> >> > > 1. Affirmation of focusing on user-level documentation of Open
>> >> >> > > MPI-specific issues. E.g., here's how OMPI's wrapper compilers
>> >> >> > > work; here's
>> >> >> > > how to use --showme, here's how to use OMPI's mpirun, here's
>> how to
>> >> >> > > set OMPI
>> >> >> > > MCA params, ...etc. A short MPI programming tutorial would be
>> ok,
>> >> >> > > but keep
>> >> >> > > it short/high level, and use it as a gateway to explaining the
>> OMPI
>> >> >> > > tools
>> >> >> > > surrounding an MPI source code (because there's books and lots
>> of
>> >> >> > > google
>> >> >> > > material on writing MPI code).
>> >> >> > >
>> >> >> > > 2. Additionally, try to make docs that can be fairly stable over
>> >> >> > > time:
>> >> >> > > stuff that won't need to be updated frequently, because
>> >> >> > > documentation tends
>> >> >> > > to suffer from bit rot. So if we can intentionally write fairly
>> >> >> > > stable docs
>> >> >> > > to start with, they'll have a longer shelf life.
>> >> >> > >
>> >> >> > > Meaning: don't document every OMPI detail. Rather, (at least to
>> >> >> > > start
>> >> >> > > with) document all the high-level OMPI concepts that haven't
>> >> >> > > changed in a
>> >> >> > > long time: ./configure && make -j 32 install, wrapper compilers,
>> >> >> > > mpirun, MCA
>> >> >> > > params, etc.
>> >> >> > >
>> >> >> > > 3. The community suggested that PDF might not be a good primary
>> >> >> > > format
>> >> >> > > (this surprised me). For example, Google scores PDFs lower than
>> >> >> > > HTML --
>> >> >> > > that's a good point; I didn't know that.
>> >> >> > >
>> >> >> > > Put differently: apparently, kids these days want to read web
>> >> >> > > pages,
>> >> >> > > not PDFs. So the question naturally of source code format was
>> >> >> > > raised -- the
>> >> >> > > old "latex can render into both PDF and HTML" issue came up. I
>> >> >> > > don't know
>> >> >> > > if anyone has tried it recently, but the HTML emitted by
>> latex2html
>> >> >> > > is
>> >> >> > > actually pretty awful/horrible/ugly. Some suggestions were
>> floated
>> >> >> > > that
>> >> >> > > might be good instead of latex (because they can render
>> >> >> > >
>> >> >> > > - Asciidoc, which renders to both HTML and PDF (and others),
>> >> >> > > http://www.methods.co.nz/asciidoc/
>> >> >> > >
>> >> >> > > - Pandoc, which will let you convert arbitrarily between
>> different
>> >> >> > > markup/markdown formats: http://johnmacfarlane.net/pandoc/
>> >> >> > >
>> >> >> > > - Markdown, a markup language:
>> >> >> > > http://daringfireball.net/projects/markdown/ (probably need to
>> >> >> > > route through
>> >> >> > > Pandoc to get PDF from Markdown)
>> >> >> > >
>> >> >> > > - Docbook, but that's basically writing XML, which feels kinda
>> >> >> > > ugly/blech.
>> >> >> > >
>> >> >> > > Thoughts?
>> >> >> > >
>> >> >> > > --
>> >> >> > > Jeff Squyres
>> >> >> > > jsquyres_at_[hidden]
>> >> >> > > For corporate legal information go to:
>> >> >> > > http://www.cisco.com/web/about/doing_business/legal/cri/
>> >> >> > >
>> >> >> > > _______________________________________________
>> >> >> > > docs mailing list
>> >> >> > > docs_at_[hidden]
>> >> >> > > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> >> >> > _______________________________________________
>> >> >> > docs mailing list
>> >> >> > docs_at_[hidden]
>> >> >> > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> >> >> _______________________________________________
>> >> >> docs mailing list
>> >> >> docs_at_[hidden]
>> >> >> http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> >> >
>> >> >
>> >> >
>> >> > _______________________________________________
>> >> > docs mailing list
>> >> > docs_at_[hidden]
>> >> > http://www.open-mpi.org/mailman/listinfo.cgi/docs
>> >
>> >
>>
>
>