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