---+!! PDF Options for "[[%URLPARAM{baseweb}%.%URLPARAM{basetopic}%][%URLPARAM{basetopic}%]]"

<div class="twikiNotification">
---+++ TWiki admins
To install and configure the !GenPdfForm:
   1. Copy this text to [[%TWIKIWEB%.GenPdfForm]] in your TWiki web.
   1. Attach profile.gif and landscape.gif to [[%TWIKIWEB%.GenPdfForm]]: do not create links, and do not show in the attachment table. 
   2. Preferences variables are used to preset the web form to the desired defaults:
	   * Explicitly define GENPDFADDON_ORIENTATION, rather than relying the default value
	   * Set GENPDFADDON_TITLETOPIC for the case that a title page is requested
		* Review the values that appear below for GENPDFADDON_PAGESIZELIST (a new variable) and modify as desired. For example, European users will want 'a4' in the list.
   3. Add a toolbar button that points to the form by editing =TWiki/templates/viewtopicactionbuttons.tmpl=:
      * Insert the PDF button in this line:<verbatim>%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"action_activatable_edit_or_create"}%%TMPL:P{"action_activatable_attach"}%TMPL:P{"action_printable"}%%TMPL:P{"action_PDF"}%%TMPL:P{"action_revisions"}%%TMPL:P{"action_backlinks_simple"}%%TMPL:P{"action_raw_or_view"}%%TMPL:P{"action_activatable_raw_edit"}%%TMPL:P{"activatable_more"}%%TMPL:END%</verbatim>
      * Add these two lines:<verbatim>%TMPL:DEF{"action_PDF"}%%TMPL:P{"PDF"}%%TMPL:P{"sep"}%%TMPL:END%
%TMPL:DEF{"PDF"}%<span><a href='%SCRIPTURLPATH{"view"}%/%TWIKIWEB%/GenPdfForm?baseweb=%WEB%&basetopic=%TOPIC%' %MAKETEXT{"title='PDF version of this topic' accesskey='d'>P&DF"}%</a></span>%TMPL:END%</verbatim>
   4. Remove or =&lt;-- hide -->= these instructions.
</div>

<!--
   * Set GENPDFADDON_PAGESIZELIST = letter, legal

"Macros":
   * Set MACRO_TWISTY_START = %TWISTY{mode="span" showlink="Show" hidelink="Hide" showimgleft="%ICONURLPATH{toggleopen-small}%" hideimgleft="%ICONURLPATH{toggleclose-small}%" }% <blockquote>
   * Set MACRO_TWISTY_END = </blockquote> %ENDTWISTY%
-->
<form action="%SCRIPTURL%/genpdf/%URLPARAM{baseweb}%/%URLPARAM{basetopic}%">
	
%TABLE{sort="off" valign="top" dataalign="top"}%
| Title page |  <select name="pdftitletopic" size=1> \
   <option value="%GENPDFADDON_TITLETOPIC%" selected>yes</option> \
   <option value="">no</option></select>  |
| Title (properly spaced) | <input size="40" name="pdftitle" value="%SPACEOUT{%URLPARAM{basetopic}%}%" /> |
| Table of contents levels |  \
<select name="pdftoclevels" size=1> \
<option value=0 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==0, selected)}%>No table of contents</option> \
<option value=1 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==1, selected)}%>1st level headings</option>   \
<option value=2 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==2, selected)}%>2nd level headings</option>   \
<option value=3 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==3, selected)}%>3rd level headings</option>   \
<option value=4 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==4, selected)}%>4th level headings</option>   \
<option value=5 %CALC{$IF(%GENPDFADDON_TOCLEVELS%==5, selected)}%>5th level headings</option>   \
</select>  |
| Numbered section headings %BR% (requires a table of contents) |  <input type="checkbox" name="pdfnumberedtoc"}%"/>  |
| Orientation | %CALC{$LISTJOIN($sp,$LISTMAP(<img src=%ATTACHURLPATH%/$item.gif> <input type=radio name=pdforientation value=$item $IF($EXACT(%GENPDFADDON_ORIENTATION%,$item), checked)> $item<br>, portrait, landscape))}% |
| Page size | %CALC{$LISTJOIN($sp,$LISTMAP(<input type=radio name=pdfpagesize value=$item $IF($EXACT(%GENPDFADDON_PAGESIZE%,$item), checked)> $item<br>, %GENPDFADDON_PAGESIZELIST%))}% |
<input type="submit" value="Generate PDF" />
</form>

---++ Command Strings
Special HTML comments can be embedded in the original document to create page breaks, override the header and footer text, and control the current media options:
%MACRO_TWISTY_START%
<DL>
<!-- NEED 1in -->
<DT><CODE>&lt;!-- FOOTER LEFT &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the left footer text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- FOOTER CENTER &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the center footer text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- FOOTER RIGHT &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the right footer text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- HALF PAGE --&gt;</CODE></DT>
<DD>Break to the next half page.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- HEADER LEFT &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the left header text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- HEADER CENTER &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the center header text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- HEADER RIGHT &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the right header text; the test is applied to the current page
 if empty, or the next page otherwise.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA BOTTOM nnn --&gt;</CODE></DT>
<DD>Sets the bottom margin of the page. The &quot;nnn&quot; string can be any
 standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new
 page if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA COLOR &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the media color attribute for the page. The &quot;foo&quot; string is any
 color name that is supported by the printer, e.g. &quot;Blue&quot;, &quot;White&quot;, etc.
 Breaks to a new page or sheet if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA DUPLEX NO --&gt;</CODE></DT>
<DD>Chooses single-sided printing for the page; breaks to a new page or
 sheet if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA DUPLEX YES --&gt;</CODE></DT>
<DD>Chooses double-sided printing for the page; breaks to a new sheet if
 the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA LANDSCAPE NO --&gt;</CODE></DT>
<DD>Chooses portrait orientation for the page; breaks to a new page if
 the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA LANDSCAPE YES --&gt;</CODE></DT>
<DD>Chooses landscape orientation for the page; breaks to a new page if
 the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA LEFT nnn --&gt;</CODE></DT>
<DD>Sets the left margin of the page. The &quot;nnn&quot; string can be any
 standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new
 page if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA POSITION nnn --&gt;</CODE></DT>
<DD>Sets the media position attribute (input tray) for the page. The
 &quot;nnn&quot; string is an integer that usually specifies the tray number.
 Breaks to a new page or sheet if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA RIGHT nnn --&gt;</CODE></DT>
<DD>Sets the right margin of the page. The &quot;nnn&quot; string can be any
 standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new
 page if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA SIZE foo --&gt;</CODE></DT>
<DD>Sets the media size to the specified size. The &quot;foo&quot; string can be
 &quot;Letter&quot;, &quot;Legal&quot;, &quot;Universal&quot;, or &quot;A4&quot; for standard sizes or
 &quot;WIDTHxHEIGHTunits&quot; for custom sizes, e.g. &quot;8.5x11in&quot;; breaks to a new
 page or sheet if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA TOP nnn --&gt;</CODE></DT>
<DD>Sets the top margin of the page. The &quot;nnn&quot; string can be any
 standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new
 page if the current page is already marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- MEDIA TYPE &quot;foo&quot; --&gt;</CODE></DT>
<DD>Sets the media type attribute for the page. The &quot;foo&quot; string is any
 type name that is supported by the printer, e.g. &quot;Plain&quot;, &quot;Glossy&quot;,
 etc. Breaks to a new page or sheet if the current page is already
 marked.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- NEED length --&gt;</CODE></DT>
<DD>Break if there is less than <CODE>length</CODE> units left on the
 current page. The <CODE>length</CODE> value defaults to lines of text
 but can be suffixed by <CODE>in</CODE>, <CODE>mm</CODE>, or <CODE>cm</CODE>
 to convert from the corresponding units.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- NEW PAGE --&gt;</CODE></DT>
<DD>Break to the next page.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- NEW SHEET --&gt;</CODE></DT>
<DD>Break to the next sheet.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- NUMBER-UP nn --&gt;</CODE></DT>
<DD>Sets the number of pages that are placed on each output page. Valid
 values are 1, 2, 4, 6, 9, and 16.
<!-- NEED 1in -->
</DD>
<DT><CODE>&lt;!-- PAGE BREAK --&gt;</CODE></DT>
<DD>Break to the next page.</DD>
</DL>
%MACRO_TWISTY_END%

Commands can also define the region of the topic that should be included in the PDF generation. Everything between these two comments will be included in the PDF generation (the rest of topic will be excluded):

	* Use =&lt;!-- PDFSTART --&gt;= to mark the starting point in the topic for PDF generation.
	* Use =&lt;!-- PDFSTOP --&gt;= to mark the stopping point in the topic for PDF generation.

There can be multiple PDFSTART and PDFSTOP comment pairs in a single topic to selectively include/exclude multiple sections of the topic in the PDF document. If no PDFSTART/PDFSTOP comment pair appears in the topic, the entire topic text is used.
