Hi David,
Sorry, I should have been a bit more specific in the email.
The tl;dr version is:
The latex files currently don't separate out the content and style
properly, and require lots of htmlonly/latexonly blocks which are
annoying to write and maintain. The html output produced is kinda ugly
and hard to read and find things in. This approach could fix both of
these! (It shouldn't change the output pdf's much at all, except to use
hyperref).
We don't have to go with tex4ht specifically (although it works well),
once we've separated out the style and content we should be able to use
any modern html-from-latex generator without too much work.
The far too long version:
This was initially prompted by seeing the large amount of work it took
Malcolm and Holly to turn the SC21 cookbook Holly had updated into a
cookbook that actually built successfully and produced the correct
output. It would be nice if scientists who aren't starlink programmers
could contribute updates to the cookbooks and documentation more easily.
There were two main issues that I think could do with addressing:
1) We don't separate out the styling from the content well in our latex
files, making it harder to write and maintain the current documentation
(particularly for e.g. cookbooks where more complex formatting is needed)
* Because we don't have a defined starlink class, everyone has
manually copied the same set of definitions into every file, and then
there are many variations on the same slight tweaks when people want to
specific styles to appear.
* Because of latex2html's requirements, any documents where people do
want more than fairly basic formatting seem to require lots of repeated
blocks, with the same content written in a different structure in an
htmlonly block and a latexonly block.
The approach I've used for these example documents doesn't use *any*
separate latex/html code in the latex source -- the same latex code
produces both documents. The configuration is instead where it should
be, in the class/style files. If the default output from tex4ht for a
particular command or environment doesn't look the way we want by
default (most are fine), we can configure that command and its css
sensibly in our class files, and it will then work properly for all
starlink html documentation. The person writing the document shouldn't
have to worry too much about the style and formatting.
2) While the current pdf output is fine (apart from needing the hyperref
package to be added in), the html output is (for me) very ugly and
actually hard to use. The insistence of latex2html on putting every
single sectioning command on a whole new page makes a lot of the
documentation very hard to follow (the kappa documentation is
particularly annoying in this way). The output is actively hard to read
on most screens
The html output from latex2html is hard to style/improve with css
styling, as latex2html wasn't written expecting modern html/css.
Many of these aspects are presumably tweakable -- but latex2html isn't
really ideal for our purposes anyway, so its not clear its worth putting
a lot of effort into improving its output if the end result would still
be not-great html and source documents with repeated htmlonly/latexonly
blocks.
Also, by separating out the style and the content properly we'll make it
much much easier to move to other documentation systems in the future if
we ever need to -- or too pick one of the other html-from-tex packages
rather than tex4ht.
(I tried tex4ht as it comes with texlive so was already available on all
my machines, and looked like the most full featured of the various
html-from-latex options. Its released under the LPPL (Latex public
project license) though rather than the GPL, so if we wanted to ship it
*and* we needed to modify the source itself (unlikely I think) there
might be a couple of extra requirements I think.)
If we do decide to move ahead with this, I'm not sure how long it would
take -- its obviously not going to be the highest priority for me (or
anyone else), but it also doesn't seem like converting a single file
takes that long. Only the very long documents or ones with complex
formatting would take some time. Obviously we'd also have to integrate
it all into the build system as well, and I don't know how much effort
that would be.
Cheers,
Sarah
David Berry wrote:
> Hi Sarah,
> So what are the specific issues that you are trying to
> fix? The new version looks fine, but it's not obvious to me why it is
> any better than the old version. A list of specific benefits would be
> interesting...
>
> David
>
> On 28 August 2014 04:38, Sarah Graves<[log in to unmask]> wrote:
>> Hi All,
>>
>> I've recently been taking a look to see if there is anyway to improve the
>> starlink latex documentation appearance, and to make it easier to write and
>> maintain.
>>
>> If anyone's interested in the results, I've put up the versions I've made of
>> sun95 and sc21 as latex, html and pdf on:
>>
>> http://www.jach.hawaii.edu/~sgraves/starlink-docupdate/
>>
>>
>> This was done by creating a draft starlink.cls file so we don't have to keep
>> replicating all the formatting defintions in every latex file, and hopefully
>> encourage a little more separation of style and content.
>>
>> I've also played about with using tex4ht instead of latex2html so we can
>> generate html output that is better looking, easier to use and doesn't
>> require lots of content repeated in latexonly/htmlonly sections of the
>> texfiles.
>>
>> I'm using mathjax for the maths, but tex4ht can generate images instead if
>> mathjax isn't well supported enough.
>>
>> I copied the formatting that Holly and Malcolm had used in sc21's most
>> recent pdf version for the style of both the pdf and html output. The html
>> output is still rather crude, but I find it easier for me to use than the
>> current output.
>>
>> The cookbooks might take a bit of manual tweaking to look good in a new
>> system, but I think most of the documents with less complex formatting would
>> be pretty straightforward to adjust. (sun95 didn't take very long to get it
>> working.)
>>
>> If anyone wants it, the code is on the docupdate branch on my fork of
>> starlink:
>>
>> http://github.com/sfgraves/starlink
>> branch: docupdate
>>
>> But I haven't tried to integrate any of this with the build system yet.
>> (I've just been running the commands manually, using the tex4ht provided by
>> texlive on my computer).
>>
>> It'd be great to hear what people think of this,
>>
>> Cheers,
>>
>> Sarah
|