Tim Jenness wrote:
> Finally tried it :-)
>
> More or less works and I note that it needs ImageMagick convert to
> function. At least it builds PNG files from the PDFs directly.
I'd forgotten to mention it uses that.
>
> I have a couple of comments:
>
> 1. I don't like setting the environment variable to point to the build
> tree. I would expect us to be setting it to something in the installed
> tree just like everything else. It could then be defined in terms of
> $STARLINK_DIR and set in the etc/profile or whatever (maybe
> conditionally on you have STARCONF_DEFAULT_PREFIX set or something so
> that you know you have a user who is building stuff). Shouldn't be a
> problem to install the latexsupport stuff into $STARLINK_DIR/share/latex
> or something.
Yes, sorry, that environmental variable setting is a horrible horrible
hack that needs a fix.
What it should do (I think) is probably install all the
applications/latexsupport/ files along with star2html, and then
a) change the environemental variables within the star2html.in script.
and b) update whatever macros call pdflatex to set texinputs to the
installed location of the latexsupport/ files.
I could try and do it, but it might be rather slow unless someone could
point me to a good guide to starlink building and autoconf (I know
embarassingly little about both of these). It seems like it should be a
fairly easy fix though, if anyone else wants to do it.
>
> 2. SUN/95 has some weirdnesses. See eg WCSADD section with long
> examples. Section 4.5 has failed because of the escaped square brackets.
Fix now commited to starstyle.4ht (for some reason it wasn't putting in
a <BR> for the \linebreak command). The sst example sections use a
no-wrap css as I assume people will have deliberately set up their line
breaks in those environments, so really long lines will look pretty bad.
> I'm not really a fan of HTML that constrains the width of the view (one
> of the advantages of HTML over PDF is that it can reflow text as you
> change your browser size...). SUN/258 PDF has some issues with the long
> author list.
>
Hmm, It will reflow if the browser window is smaller than its width --
it just sets a max-width. I personally hate web pages that don't set a
max width on their main content -- its so frustrating to have to keep
resetting the window size or the css just to get a human readable page,
given that different sites will all have different amounts of content in
their sidebars.
The main problem to my mind with the reflowing is that we frequently
have a lot of large blocks of text formatted as verbatim (so set up not
to wrap), which will often force scroll bars if you set the page much
narrower than the default. The rest of the window reflows fine.
There's some other issues with the css page styling -- particularly the
table of contents -- that I'll hopefully get time to fix at some point.
>
> tex2ht is incredibly fast though. Absolutely amazed me how fast SUN/95
> built.
>
> --
> Tim Jenness
>
>
> On Mon, Nov 24, 2014 at 8:49 AM, Tim Jenness <[log in to unmask]
> <mailto:[log in to unmask]>> wrote:
>
> I can't see any reason not to merge this if everything will happen
> incrementally as documents are migrated from new to old.
>
> On Thu, Nov 20, 2014 at 11:19 PM, Sarah Graves
> <[log in to unmask] <mailto:[log in to unmask]>> wrote:
>
> Hi Tim (and everyone else)
>
> Tim Jenness wrote:
>
> Any chance this new conversion code can be committed so that
> star2html
> can be modified? This would let people migrate documents one
> at a time.
>
>
> Sorry for taking so long to get back to you, I didn't have much
> of a chance to work on this since the summer.
>
> Following up on your suggestion, I have slightly tweaked
> star2html.in <http://star2html.in> so that star2html will call
> 'htlatex' instead of latex2html if the first line of the file is
> \documentclass[<options>]{__starlink}. Otherwise it will build
> as now using latex2html.
>
> This seems to work fine with the build system. Current examples
> of the html and pdf output (produced with the usual make command
> can be found again at:
>
> http://www.jach.hawaii.edu/~__sgraves/starlink-docupdate/
> <http://www.jach.hawaii.edu/~sgraves/starlink-docupdate/>
>
> I've updated my starlink branch 'docupdate' on my github repo
>
> https://github.com/sfgraves/__starlink
> <https://github.com/sfgraves/starlink>
>
> so that is now up-to-date with the current starlink master. In
> this branch, the normal build system is working fine and
> (assuming you have tex4ht/htlatex installed through e.g. a
> recentish texlive) it will happily build the new-style documents
> as well as the old.
>
> The class file, a couple of style-files, the tex4ht
> configuration files and css and a README are located in
> applications/latexsupport/
>
> Unfortunately, at the moment you have to set a couple of extra
> environmental variables manually. These should be in the build
> system, I just wasn't sure how to include them.
> To build at the moment, you need to have:
>
> export
> TEXINPUTS=$__YOURSTARLINKCHECKOUT/__applications/latexsupport//:
> export
> TEX4HTENV=$__YOURSTARLINKCHECKOUT/__applications/latexsupport/__tex4ht.env
> export
> TEX4HTHTF=:$__YOURSTARLINKCHECKOUT/__applications/latexsupport/:
> (note weird syntax in that last one)
>
> in your path.
>
>
> What is the feeling on integrating this new doc system into
> starlink proper?
>
> Arguments for (not in any particular order):
>
> 1) No longer require irritating latexonly/htmlonly sections that
> are cumbersome to write and hard to maintain.
>
> 2) writing latex documentation has a much lower barrier to entry
> -- you can write it much more like a normal latex document.
> Even minipages should mostly work! It would be nice to make it
> less intimidating for our JAC support scientists to fix up
> cookbooks etc. themselves.
>
> 3) html output that looks sensible.
>
> 4) By maintaining a standard starlink latex class, we won't have
> to update everything in a bajillion places if we want to change
> the standard style.
>
> 5) pdf output now has html links and hyperrefs, and a
> table-of-contents you can view in the sidebar in normal pdf viewers.
>
> 6) Our html documentation will reflect the fact that this
> software is a currently developed project, instead of looking
> horribly dated and giving a poor impression of the work.
>
> 7) We don't have to do it all at once -- we can improve the
> documents people actually use soonish, and only get round to the
> older ones as time permits.
>
> 8) We can have mathjax output instead of pngs for maths.
>
> Arguments against:
>
> 1) People will require tex4ht to build our documentation. i.e.
> ancient texlive installs will not work.
>
> 2) TeX4HT has some issues (its occasionally irritating to
> configure, the documentation could be a bit better, and the guy
> who did most of the work on it died a few years ago -- its still
> being developed, but not nearly as actively). However, our
> actual documents won't contain *any* tex4ht specific code -- if
> anyone wants to move to any of the other latex->html options,
> they wouldn't have do anything but write their own configuration
> options and change the build system, rather than redo any
> documentation itself.
>
> The documents I've updated so far are SC21 (SCUBA-2 cookbook),
> SUN258 (SMURF guide) and SUN95 (KAPPA).
>
> They weren't too bad to do -- I wrote a very-poor perl script
> (in applications/latexsupport/star__link_perl_fixup.pl
> <http://starlink_perl_fixup.pl>) that attempts to remove some of
> the cruft, then I went through and rationalised some of the
> odder bits of latex, and replaced things like \tt commands with
> \texttt, checked all of the htmlonly stuff was removed etc.
>
> If we decide to include this, then I need to write a quick
> example document for starlink.cls (including a couple of useful
> environments I've defined, the basic starlink-specific commands
> to set up the titles etc). We also should probably decide which
> of the various macros are being used by lots of documents and
> should be in the class.
>
> (The appearance of the html is mostly just in the css, so if
> anyone has any good thoughts on improvements they'd be very
> welcome. I just modelled the pdf and html off of SC21's
> appearance in the last starlink release.)
>
> Sarah
>
> On Thu, Aug 28, 2014 at 5:38 PM, Tim Jenness
> <[log in to unmask] <mailto:[log in to unmask]>
> <mailto:[log in to unmask]
> <mailto:[log in to unmask]>>__> wrote:
>
>
>
>
> On Wed, Aug 27, 2014 at 8:38 PM, Sarah Graves
> <[log in to unmask] <mailto:[log in to unmask]>
> <mailto:[log in to unmask]
> <mailto:[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/
> <http://www.jach.hawaii.edu/~__sgraves/starlink-docupdate/>
>
> <http://www.jach.hawaii.edu/~__sgraves/starlink-docupdate/
> <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 happy to go with whatever you choose.
>
> I'm using mathjax for the maths, but tex4ht can generate images
> instead if mathjax isn't well supported enough.
>
>
> I'm always happy to insist that people use a reasonably new
> browser.
> If it works on Safari, Chrome and Firefox that's fine with me.
>
> 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).
>
>
> The build system tweaks would be trivial (the latex2html
> stuff is in
> a single place).
>
> It'd be great to hear what people think of this,
>
>
> +100 from me. Latex2html drives me potty, as does the
> bizarre early
> decision not to use a style file for all the document templates.
>
> Have fun with SUN/66 if you want a challenge.
>
> Note that star2html specifically runs latex2html to create huge
> numbers of pages. Not sure why.
>
> The real trick is working out how to do the work
> incrementally. A
> lot of it is a tad repetitive (but should be a bit easier
> now that
> we use PDFs everywhere) and there are older documents that
> don't use
> the standard templates [I keep meaning to "obsolete" some of the
> more bizarrely irrelevant documents that are currently
> installed;
> I'm thinking that SUN/20 is probably irrelevant :-) ]
>
> Can we manage this by using star2html to do the conversion,
> as now,
> and having it look in the tex file for the
> usepackage{starlink} line
> and if it finds it it calls tex2ht directly and otherwise it
> does
> the classical latex2html conversion? That would be by far the
> easiest way to do this and can let me fix up a document each
> evening
> until we get to the prize of having it all done (not that I'm
> volunteering to do one per night).
>
> --
> Tim Jenness
>
>
>
>
|
