starlink
starlink copied to clipboard
Starlink
Issues with new latex style
In 289b69db59cf5af276f7014bec7fb96c340883f2 SUN/209 was converted to use the new latex style but there are two outstanding problems:
- The document comes with private SST-like commands that need to be updated to the new SST look and feel (currently they are squashed together)
- There are many unresolved label references that will cause "??" to appear in the HTML version.
I should rename this issue to track latex class file issues. SUN/92 has its Figure 1 messed up with the new class (also a latex diagram). Worked fine before I updated it.
Many latex documents use a \noteroutine macro for printing out summaries of the API. Would be nice to unify these, maybe creating a \sstnoteroutine and then migrating the documents over.
The subsections of the classified commands in SUN/95 are hard to see.
The size of the SST parameter headings look too small in html. They are smaller than the description that follows.
SUN/261(IRQ) is okay but @dsberry IRQ_ADDQN talks about IRQ_SETQC which is a subroutine that does not seem to exist (it triggers a latex warning).
SUN/92: I think I've fixed the picture issue in commit eabdb704a338 It just required the unitlength to be set before creating the picture -- this was in one of the sections that starlink_fixup_perl removes. The appearance in the html output could probably be improved, it looks a bit low-res.
Also @dsberry, Appendix P is not being created when make_sun238.csh executes in kaplibs.
PS @dsberry I'm explicitly not upgrading the AST documents. I'm leaving those ones to you.
OK - I'll do AST. Do you have a list of standard changes that need to be made to each doc, or do I work it out by looking at the commits you've been making? A cursory glance suggests it's a fairly involved process. BTW - I've made the IRQ and KAPLIBS changes you pointed out.
There's a perl script in latexsupport that attempts to remove the most common bits of the prologue and put the correct class and various fix ups in.
I usually run that and then try to run pdflatex and see if it breaks anywhere. Most standard latex should be reasonable. The class file still needs some improvements though.
regarding the script, you always have to clean up the prologue a bit when you are done and remove the abstract and stuff after scfrontmatter. Not hard though. Then you have to go and sort out any verbatim paragraphs and use small environments rather than \small. Then take a look at the PDF and tweak it a bit.
@sfgraves we need to address the optional nature of \stardocversion and \stardocmanual. System Notes won't have a \stardocversion because they aren't generally talking about a library or application so it makes no sense. Abstracts are going to get a bit limited as well so we need to make these three items optional.
This terminalv environment has turned each of my multi-line Fortran code extracts into a single long lines in Redman/Redmond style. Please @sfgraves can it respect line feeds and indentation.
@MalcolmCurrie it does act exactly like a verbatim environment so I'm a bit confused. Can you send me an example of something that is not working. I've converted many documents by now and they all use terminalv.
I've got the PCS docs ready to go pending resolution of the stardocversion and stardocmanual issue. SUN/61 (TRN) is also ported but the conversion to HTML doesn't work properly with the heavy math usage and latex diagrams. I can push what I have of TRN if people want to take a look (it does do the conversion, just not very well).
I've added in a 'noabs' class option, and set stardocversion and stardocmanual to default to a space. We may want to tweak the title formatting a bit at some point, but this seems to look okay.
If a lot of documents really shouldn't have an abstract, we could also do something more clever and detect if the content of \stardocabstract is blank. Not sure its worth it though.
@timj I'd be interested in knowing where SUN/61 is breaking, particularly with the maths.
@timj http://www.starlink.ac.uk/devdocs/sun114.htx/node13.html, but something else has gone wrong with that build in that the navigation controls are late2xhtml style.
Note that the old latex2html files are not deleted when you rerun with the new style. node13.html is a latex2html output file isn't it? tex4ht does not use that naming scheme.
You want this URL: http://www.starlink.ac.uk/devdocs/sun114.htx/sun114se5.html#x6-140007 for that page.
Yup -- if you are in an existing install, there's no process to clean out the old html pages. It looks odd because when you view them you pick up the css from the new version, but the html from the old version.
Yes I hadn't noticed the old style last night, but it was obvious today but got to the correct version starting from the top (sun114.html).
We need the make world and make install to clean up previous versions.
@sfgraves for SC/3 487eaf0534bedb85ea987efb3a336affb930d9d9 I had to use negative \vspace in the title picture element to compensate for the extra space taken up by the lack of software version and manual type.
@sfgraves I'm looking at SUN/259 (in SMURF) and pdflatex refuses to deal with underscores in equations:
\begin{equation}
MAP\_WDTH \,=\, NO\_Y\_MAP\_PNTS \times CELL\_Y
\end{equation}
The command just hangs there until I ctrl-C:
) [1]^C
! Interruption.
l.335 NSCAN \times NO\_
SCAN\_PNTS
?
If I remove the \_ everything works. Obviously this all worked before I switched to the starlink class. Any thoughts? I'm using:
This is pdfTeX, Version 3.14159265-2.6-1.40.15 (TeX Live 2014) (preloaded format=pdflatex)
restricted \write18 enabled.
entering extended mode
Damn, yes, I know what this is.
Previously, we didn't use any hyperrefs inside the latex document, and the sst routine didn't turn the title of the routine into a label when running latex. Now of course we are providing hyperlinks inside the pdf, so I set a label and an xlabel with the name of the title of the routine (as was always done in html), and all the references link to that
Unfortunately, our routine titles have lots of escaped underscores in them, and (pdf?)latex can't handle escaped underscores in labels/refs.
I got around this by putting in a line in starstyle.sty to force _ to be a \string_ , and I think this is now what's breaking _ in math mode.
I think I can fix this in this case easily by adding an 'ifmath' check to that renewcommand -- I'll commit that now if it works.
I'm a bit worried we'll come up against other issues based on this though. I'm not sure this method of handling it is really ideal...
I haven't looked at the style file, to see what's happening where, but if you set \catcode```\_=11 at a suitable place, then underscore will become just a plain character, as opposed to an subscript indicator. However that character won't appear as an actual underscore in a roman font, so there are other games necessary.
If you can prepare a minimal test case, I might be able to work something out.
