Issues with new latex style

[timj]

In 289b69db59cf5af276f7014bec7fb96c340883f2 SUN/209 was converted to use the new latex style but there are two outstanding problems:

1. 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)
2. There are many unresolved label references that will cause "??" to appear in the HTML version.

[timj]

SSN/4 has trouble with Figure 2 as well (a latex diagram).

[timj]

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.

[timj]

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.

[MalcolmCurrie]

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.

[timj]

Are they the things that use \noteroutine?

[MalcolmCurrie]

No. I was going by the title.

[timj]

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).

[sfgraves]

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.

[timj]

Also @dsberry, Appendix P is not being created when make_sun238.csh executes in kaplibs.

[sfgraves]

SSN/4 is also fixed I believe (same fix as for SUN/92)

[timj]

PS @dsberry I'm explicitly not upgrading the AST documents. I'm leaving those ones to you.

[dsberry]

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.

[sfgraves]

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.

[timj]

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.

[timj]

@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.

[MalcolmCurrie]

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.

[timj]

@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.

[timj]

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).

[sfgraves]

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.

[sfgraves]

@timj I'd be interested in knowing where SUN/61 is breaking, particularly with the maths.

[MalcolmCurrie]

@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.

[timj]

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.

[timj]

You want this URL: http://www.starlink.ac.uk/devdocs/sun114.htx/sun114se5.html#x6-140007 for that page.

[sfgraves]

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.

[MalcolmCurrie]

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.

[timj]

@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.

[timj]

@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

[sfgraves]

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...

[timj]

SUN/259 now works for me.

[nxg]

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.

[timj]

As noted in commit 8b70ea05231de374ff039d3c350f6ae0b568c5a5 the description lists and equations on pages 7/8 don't convert to HTML correctly.

[timj]

Also, tex4ht seems to ignore angle modifiers to \includegraphics.

[timj]

In datacube SUN/237 the enumerated list at the start doesn't come out right in HTML.

[timj]

I'm not convinced that calling the standard Starlink figure display command \myfig is a good idea. SC/16 had its own version and that took me a while to work out.

Also, SC/16 has problems in section 5.2 with a terminalv environment suddenly changing itself into math mode when it sees a \[.

[timj]

• I am wondering why terminalv doesn't include a small environment. I end up having to add one for a lot of the output (and SUN/139 CCDPACK needs it) and I'm thinking that a latexonly small would be an appropriate default (although I've now mostly obviated the need for it by adding it manually).
• Why isn't polka.tex (POLPACK) a SUN?

[timj]

SC/9 has an issue with the figures and an issue with the first Display example.

[dsberry]

polka.tex is not a sun because it's not a note for users (as in sUN) - it's the source for the polka help system.

[timj]

@sfgraves did you change \htmladdnormallink to always write a footnote? That was what \htmladdnormallinkfoot was for. SC/15 is full of footnotes because of this.

[timj]

SUN/1 has raised a couple of issues with index creation and labeling of items. Regarding the labeling, it may well be easiest to replace the description lists with normal subsections.

See 65bd8c8877c98229734597102a94f985e5fc4a01

[timj]

Remaining documents are AST, TSP and SLALIB. The latter two have their own variants of SST.

[dsberry]

I'll add converting the AST docs to my list of things to do in the long Hilo evenings....

David

On 14 January 2015 at 16:26, Tim Jenness notifications@github.com wrote:

Remaining documents are AST, TSP and SLALIB. The latter two have their own variants of SST.

— Reply to this email directly or view it on GitHub https://github.com/Starlink/starlink/issues/43#issuecomment-69943565.

[timj]

@dsberry I'm happy to make the attempt if it lets you focus on the AST A&C paper... :smile:

[timj]

The AST docs were done in 1759d0a3739ad9f89bd70d52a9afeef3e7f2be80 but there are issues with the labels (essentially when the name includes parens since \sstlabel can't be used as SST already creates a label).

[sfgraves]

I was having a bit of trouble identifying all the issues I still need to fix up, so I think I've summarised below everything from this long issue. Please add if I've missed anything that hasn't been fixed already.

Still To Do

• [x] commit doc on using new style file.
• [ ] Unify \noteroutine, \classitem and \menuitem so there is only command for these & then fix up existing documents and add to latexsupport doc.
• [x] subsections of the classified commands in SUN/95 are hard to see.
• [x] The size of the SST parameter headings look too small in html. They are smaller than the description that follows. (They don't look smaller to me -- I'll need some examples of this before I can fix it)
• [x] optional nature of \stardocversion and \stardocmanual ( SC/3 487eaf0 )
• [x] SSN/72 in new latex: The description lists with equations on pages 7/8 don't convert properly to HTML. Fixed in 0d55fa91c35
• [x] tex4ht seems to ignore angle modifiers to \includegraphics. Instead: update instances of angle modifiers to includegraphics with correctly rotated images...
• [x] add small environment to terminalv in latex
• [x] SC/9 has an issue with the figures and an issue with the first Display example. I believe this is fixed in e1149eef59fd
• [x] SUN/1 has raised a couple of issues with index creation and labeling of items. Regarding the labeling, it may well be easiest to replace the description lists with normal subsections. See 65bd8c8877c
• [x] \htmladdnormallink vs \htmladdnormallinkfoot
• [x] \myfig and \myfigduo are problematic (confugins name, and also breaks star2html's attempt to copy the images)
• [x] SC/16 has problems in section 5.2 with a terminalv environment suddenly changing itself into math mode when it sees a [. Fixed in 1ba87e8984b206
• [x] Labels in AST docs (see 1759d0a)
• [x] Change \sstmacro and \sstmacronolabel to \sstroutine and \sstroutinenolabel (see 64688b91325a4c81 and associated comments)
• [x] SUN/61 (in libraries/trn) doesn't work.

[sfgraves]

Re support of angle modifiers to includegraphics in html output:

I could try and do it using CSS, but from a quick attempt I think it might make the amount of space allocated for the image in html a bit weird. It would be a lot easier if people could rotate the images themselves rather than doing it in tex. There's only about 9 instances of it in our codebase I think, so my plan is to change those rather than support this with tex4ht.

[timj]

Noting it in the SUN is fine. I've been de-rotating them as I find them. Just needs a warning so that people don't look at the PDF and assume it's all going to be fine.