ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

On 01/10/2011 05:28 PM, Kevin Godby wrote:
> Hey, Kyle.
>
> On Mon, Jan 10, 2011 at 12:04 PM, Kyle Nitzsche
> <kyle.nitzsche@xxxxxxxxxxxxx>  wrote:
> > Hi,
> > My screenshots are getting pushed to the next page well after relevant text,
> > despite the order of the LaTex commands in the tex file.
> *snip*
> > What's the MAGIC?
> I'm afraid I don't have time right now to go into the vagaries of
> LaTeX's float placement algorithm, but what you need to know at the
> moment is that the screenshots are using LaTeX's figure environment.
> The figure environment is a float.  Floats can be moved around by
> LaTeX to appease its algorithms.
http://en.wikibooks.org/wiki/LaTeX/Floats,_Figures_and_Captions

I start to see how it works. For example:
 * in ubuntu-developer-manual.cls
 * where it specifies the \screenshot command (or environment.. not sure of the 
LaTeX terminology here)
 * I can modify the figure 'environment' placement specifier to, for example, 
place figures at the bottom of a page, with the '[b]' in the last line of this:
\newcommand{\screenshot}[4][htbp!]{%
  \ifvmode\else\unskip\fi%
  \IfFileExists{../images-\@ubuntu@language@code/#2}{%
    
\savebox{\screenshotgraphic}{\includegraphics[scale=\strip@pt\screenshotscale]{../images-\@ubuntu@language@code/#2}}%
    \ifthenelse{\wd\screenshotgraphic>\textwidth}{%
      \begin{figure*}[b]%

Kevin:
Placing figures is difficult in lots of tool chains. My gut feeling is that 
since we don't necessarily have scheduled time and person-power to go through 
the text and plcae figures *every* time we need to create a pdf, and since a 
misplaced figure is *worse* than extra whitespace on a page from the point of 
reader comprehension, we should consider a default placement of HERE (with 
"[h]") in the above.

In other words, by default, the figure should appear where the author placed it 
in the text.

That way, anyone at anytime can build a pdf without having to work through the 
whole thing.

What do you think?
> Here's what I'd recommend:  Don't fret about the placement of the
> screenshots just yet.  Go ahead and drop the \screenshot commands into
> the code where you think the screenshots should appear (or where
> they're most relevant).  After all the text has been written, we can
> start negotiating with LaTeX about the placement of the screenshots.
>
> If you spend time right now trying to coerce LaTeX into placing a
> screenshot in some particular location, you'll be upset when someone
> else's earlier text messes up a page break and throws your float
> placements off again.
>
>
> *snip*
> > \screenshot{bzr-divergence.png}{bzr-divergence}{Trunk Branch is Diverged
> > from Local Branch}
> Please use the ss: prefix for the label argument:
>
>    \screenshot{bzr-divergence.png}{ss:bzr-divergence}{Trunk Branch is
> Diverged from Local Branch}
>
> This helps ease troubles later if we want to cross-reference a section
> titled "bzr divergence" (\label{sec:bzr-divergence}) and gives an
> indicator as to what you're referencing (a screenshot, section, etc.).
ack
> --Kevin