Changeset 6464


Ignore:
Timestamp:
02/21/10 23:48:06 (2 years ago)
Author:
GeorgeClark
Message:

Item8586: Restructure documentation so displays better in pdf format. Also document the rename of GenPDF.pm

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/GenPDFAddOn/data/System/GenPDFAddOn.txt

    r6444 r6464  
    2525   * Another option is to create a global variable that inserts a PDF ICON in the document. The following variable is expanded in the upper-right corner of this page. You can click it to get a PDF of this page. If you set this in your Main.SitePreferences topic, it can be used in any topic. 
    2626<verbatim> 
    27    * Set GENPDFLINK=<span style="margin:0 0 2em 5em; width:64px height:64px; text-align:center; float:right">[[%SCRIPTURL{"genpdf"}%/%WEB%/%TOPIC%?%QUERYSTRING%][<img src="%PUBURL%/System/GenPDFAddOn/pdf-64.gif">]]</span> 
     27   * Set GENPDFLINK=<span style="margin:0 0 2em 5em; width:64px height:64px; text-align:center; float:right"> 
     28   [[%SCRIPTURL{"genpdf"}%/%WEB%/%TOPIC%?%QUERYSTRING%][<img src="%PUBURL%/System/GenPDFAddOn/pdf-64.gif">]] 
     29   </span> 
    2830</verbatim> 
    2931   * You may also choose to replace the Printable (?skin=print) targets in your favourite skin with 
    … …  
    3638This version of the !AddOn also ships with a simple !GenPDFPlugin helper plugin.  It will render the %<nop>GENPDF% macro as a clickable link to the pdf version of the topic. 
    3739 
    38 %TABLE{sort="off"}% 
    39 | *Write* | *To get<br />(Simulated)* | *If Installed* | 
    40 | %<nop>GENPDF% | %SCRIPTURL{"genpdf"}%/System/GenPDFAddOn | %GENPDF% | 
    41 | %<nop>GENPDF{"System.WebHome"}% | %SCRIPTURL{"genpdf"}%/System/WebHome | %GENPDF{"System.WebHome"}% | 
    42 | %<nop>GENPDF{"System.WebHome" link="WebHome"}% | [[%SCRIPTURL{"genpdf"}%/System/WebHome][WebHome]] | %GENPDF{"System.WebHome" link="WebHome"}% | 
     40*Write* %<nop>GENPDF%  
     41   * *Simulated:* %SCRIPTURL{"genpdf"}%/System/GenPDFAddOn  
     42   * *If Installed:* %GENPDF%  
     43 
     44*Write* %<nop>GENPDF{"System.WebHome"}% 
     45   * *Simulated:* %SCRIPTURL{"genpdf"}%/System/WebHome 
     46   * *If Installed:* %GENPDF{"System.WebHome"}%  
     47 
     48*Write* %<nop>GENPDF{"System.WebHome" link="WebHome"}%  
     49   * *Simulated*: [[%SCRIPTURL{"genpdf"}%/System/WebHome][WebHome]]  
     50   * *If Installed*: %GENPDF{"System.WebHome" link="WebHome"}%  
    4351 
    4452---++ Configuring the Script 
    … …  
    5058The following table shows the various configuration variables and their meaning. The first column gives the variable to use if passed in the URL. The second column shows the variable to use if using a Foswiki preference variable (i.e. Set VARIABLE = ). The third column gives the default value if neither the URL nor Foswiki preference variable is used. Note that URL variables have precedence over Foswiki preference variables. 
    5159 
     60%X% Foswiki preference variables *must be prefixed with GENPDFADDON*. 
     61_%Prefixes are omitted from this table to improve the layout_ 
     62 
    5263_The HTMLDOC software and related variables, see the HTMLDOC documentation at http://www.htmldoc.org/ for detailed information_ 
    53  
     64<small> 
    5465%TABLE{ cellpadding="3" columnwidths="15%, 15%, 15%, 15%, 40%"}% 
    5566| *URL Variable* | *Foswiki Preference Variable* | *Default Value* | *Example* | *Explanation* | 
    56 | =pdfbanner= | GENPDFADDON_BANNER | | Foobar Documentation System | Used to override the banner of a title page. | 
    57 | =pdftitle= | GENPDFADDON_TITLE | | Writing Foobars | | 
    58 | =pdfsubtitle= | GENPDFADDON_SUBTITLE | | A short guide to creating foobar documents | | 
    59 | =pdfheadertopic= | GENPDFADDON_HEADERTOPIC | | !GenPDFHeaderFooterTopic | The name of a topic that defines headers and footers using &lt;-- HEADER LEFT "foobar" --&gt; syntax | 
    60 | =pdftitletopic= | GENPDFADDON_TITLETOPIC | | !GenPDFTitleTopic | The name of a topic that defines the layout of the title page | 
    61 | =pdftitledoc= | GENPDFADDON_TITLEDOC | | | The name of an attachment of =pdftitletopic=; if specified ,becomes the title page. Allows images - see htmldoc manual | 
    62 | =skin= | GENPDFADDON_SKIN | =pattern= | =nat= | Default skin to use for PDF generation | 
    63 | =cover= | GENPDFADDON_COVER | =print= | =print.nat= | Default cover to use for PDF generation | 
    64 | =rev= | | | =rev=10= | Generate a PDF from a prior topic revision. This disables =pdfrecursive= | 
    65 | =pdfrecursive= | GENPDFADDON_RECURSIVE | =undef= | =on= | Include children of the base topic in the PDF | 
    66 | =pdfformat= | GENPDFADDON_FORMAT | =pdf14= | =pdf12= | HTMLDOC output format | 
    67 | =pdftoclevels= | GENPDFADDON_TOCLEVELS  | =5= | =3= | Number of levels to include in the PDF table of contents (use 0 to disable the generation of a table of contents). Note that HTMLDOC generates a table of contents based on HTML headers in the page. | 
    68 | =pdfpagesize= | GENPDFADDON_PAGESIZE | =a4= | =letter= | The page size for PDF output | 
    69 | =pdforientation= | GENPDFADDON_ORIENTATION | =portrait= | =landscape= | The page orientation (e.g. landscape or portrait) | 
    70 | =pdfwidth= | GENPDFADDON_WIDTH | =860= | =1060= | The pixel width of the browser (used to scale images--images wider than this will be truncated) | 
    71 | =pdfheadershift= | GENPDFADDON_HEADERSHIFT | =0= | =+3= | Shift all headers up or down (for negative values) by this amount (e.g. H1 would become H3 for a value of 2). Can also be set to =auto= to cause headers to shift according to the depth of recursive rendering | 
    72 | =pdfkeywords= | GENPDFADDON_KEYWORDS | =%<nop>FORMFIELD{"KeyWords"}%= | 'foo, bar, baz, zip' | Used for PDF Keywords META info to help search engines | 
    73 | =pdfsubject= | GENPDFADDON_SUBJECT | =%<nop>FORMFIELD{"TopicHeadline"}%= | 'Foobar document creation' | Used for PDF Subject META info to help search engines | 
    74 | =pdftoctitle= | GENPDFADDON_TOCTITLE | | =Contents= | See http://www.htmldoc.org/ Default is to use the htmldoc provided string "Table of Contents". Note that a current limitation is that strings containing embedded spaces are not passed correctly. | 
    75 | =pdftocheader= | GENPDFADDON_TOCHEADER | =...= | =l..= | See http://www.htmldoc.org/ | 
    76 | =pdftocfooter= | GENPDFADDON_TOCFOOTER | =..i= | =.i.= | See http://www.htmldoc.org/ | 
    77 | =pdfheader= | GENPDFADDON_HEADER | | .1. | Specify content of header, see http://www.htmldoc.org | 
    78 | =pdffooter= | GENPDFADDON_FOOTER | | .1. | Specify content of footer, see http://www.htmldoc.org | 
    79 | =pdfheadfootfont= | GENPDFADDON_HEADFOOTFONT | | Helvetica-Bold | Font specification for headers and footers. | 
    80 | =pdfheadfootsize= | GENPDFADDON_HEADFOOTSIZE | | 12 | Sets the size of the header and footer text in points (1 point = 1/72nd inch) | 
    81 | =pdfbodyimage= | GENPDFADDON_BODYIMAGE | | http://my.server.com/path/to/background.jpeg | The image that will appear tiled in the background of every page | 
    82 | =pdflogoimage= | GENPDFADDON_LOGOIMAGE | | http://my.server.com/path/to/logo.jpeg | The logo that will appear in a header or footer if you specify 'l' in the string (see http://www.htmldoc.org) | 
    83 | =pdfnumberedtoc= | GENPDFADDON_NUMBEREDTOC | =undef= | True | Option flag for getting numbered headings and Table of Contents. Set it to anything for true. | 
    84 | =pdfduplex= | GENPDFADDON_DUPLEX | =undef= | True | Option flag to set up the document for duplex printing. Headers and footers will swap position on alternating pages. Set it to anything for true. | 
    85 | =pdfpermissions= | GENPDFADDON_PERMISSIONS | =undef= | print,no-copy | PDF Security permissions to disable print/copy etc. By default the PDF is not protected. | 
    86 | =pdfmargins= | GENPDFADDON_MARGINS | =undef= | =top:0.5in,bottom:2.5cm,<br />left:12pt,right:15mm= | Specify the page margins (white space to edge of page) | 
    87 | =pdfbodycolor= | GENPDFADDON_BODYCOLOR | =undef= | =#CCff99= | Specify the background colour of all pages | 
    88 | =pdfstruct= | GENPDFADDON_STRUCT | =book= | =webpage= | use =book= for structured topics, i.e. when rendering a bunch of topics recursively; use =webpage= when printing a topic without a specific heading structure, i.e. if it is just a normal webpage or if it has got a special VIEW_TEMPLATE | 
    89 | =pdfcopyright= | GENPDFADDON_COPYRIGHT | =%%NOP%WEBCOPYRIGHT%= | =Copyright 2009= | Should PDF Metadata include the Foswiki %%NOP%WEBCOPYRIGHT% or another value. If set to 0, copyright is excluded. If set to any other string, the string is included in the metadata. Htmldoc has a bug and appends the copyright to the author metadata, which can break some document management systems that depend on the metadata. Set to =0= to exclude the copyright from the PDF metadata. | 
    90 | =pdfdebug= | GENPDFADDON_DEBUG | =0= | =1= | Include debug messages and don't clean up temporary files after execution | 
    91 | =pdffirstpage= | GENPDFADDON_FIRSTPAGE | =toc= | | First page viewer will open: =toc= table of contents; =p1= first page; =c1= first chapter. | 
    92 | =pdfdestination= | GENPDFADDON_DESTINATION | =view= | | Output to browser window or save-as prompt | 
    93 | =pdfpagelayout= | GENPDFADDON_PAGELAYOUT | =single= | | View's initial presentation layout: =single=, =one=, =twoleft=, =tworight= | 
    94 | =pdfpagemode= | GENPDFADDON_PAGEMODE | =outline= | | Viewer's initial presentation mode: =outline=, =document=, =fullscreen= | 
    95 | =pdfcompress= | GENPDFADDON_COMPRESS | | =9= | Set compression level of the document. 1=minimum, 9=maximum, =none= to disable compression | 
    96 | =pdfjpegquality= | GENPDFADDON_JPEGQUALITY | | =80= | Set JPEG image quality. Lower quality is higher compression. Set to =none= to disable JPEG image compression | 
     67| pdfbanner | _BANNER | | Foobar Documentation System | Used to override the banner of a title page. | 
     68| pdftitle | _TITLE | | Writing Foobars | | 
     69| pdfsubtitle | _SUBTITLE | | A short guide to creating foobar documents | | 
     70| pdfheadertopic | _HEADERTOPIC | | !MyHeader | The name of a topic that defines headers and footers using &lt;-- HEADER LEFT "foobar" --&gt; syntax.  See [[Sandbox.GenPDFExampleHeaderFooterTopic][example]] | 
     71| pdftitletopic | _TITLETOPIC | | !MyTitle | The name of a topic that defines the layout of the title page   See [[Sandbox.GenPDFExampleTitleTopic][example]] | 
     72| pdftitledoc | _TITLEDOC | | | The name of an attachment if specified ,becomes the title page. Allows images - see htmldoc manual | 
     73| skin | _SKIN | pattern | nat | Default skin to use for PDF generation | 
     74| cover | _COVER | print | print.nat | Default cover to use for PDF generation | 
     75| rev | | | rev=10 | Generate a PDF from a prior topic revision. This disables =pdfrecursive= | 
     76| pdfrecursive | _RECURSIVE | | on | Include children of the base topic in the PDF | 
     77| pdfformat | _FORMAT | pdf14 | pdf12 | HTMLDOC output format | 
     78| pdftoclevels | _TOCLEVELS  | 5 | 3 | Number of levels to include in the PDF table of contents (use 0 to disable the generation of a table of contents). Note that HTMLDOC generates a table of contents based on HTML headers in the page. | 
     79| pdfpagesize | _PAGESIZE | a4 | letter | The page size for PDF output | 
     80| pdforientation | _ORIENTATION | portrait | landscape | The page orientation (e.g. landscape or portrait) | 
     81| pdfwidth | _WIDTH | 860 | 1060 | The pixel width of the browser (used to scale images--images wider than this will be truncated) | 
     82| pdfheadershift | _HEADERSHIFT | 0 | +3 | Shift all headers up or down (for negative values) by this amount (e.g. H1 would become H3 for a value of 2). Can also be set to =auto= to cause headers to shift according to the depth of recursive rendering | 
     83| pdfkeywords | _KEYWORDS | %<nop>FORMFIELD<br />{"KeyWords"}% | 'foo, bar, baz, zip' | Used for PDF Keywords META info to help search engines | 
     84| pdfsubject | _SUBJECT | %<nop>FORMFIELD<br />{"TopicHeadline"}% | 'Foobar document creation' | Used for PDF Subject META info to help search engines | 
     85| pdftoctitle | _TOCTITLE | | Contents | See http://www.htmldoc.org/ Default is to use the htmldoc provided string "Table of Contents". Note that a current limitation is that strings containing embedded spaces are not passed correctly. | 
     86| pdftocheader | _TOCHEADER | ... | l.. | See http://www.htmldoc.org/ | 
     87| pdftocfooter | _TOCFOOTER | ..i | .i. | See http://www.htmldoc.org/ | 
     88| pdfheader | _HEADER | | .1. | Specify content of header, see http://www.htmldoc.org | 
     89| pdffooter | _FOOTER | | .1. | Specify content of footer, see http://www.htmldoc.org | 
     90| pdfheadfootfont | _HEADFOOTFONT | | Helvetica-Bold | Font specification for headers and footers. | 
     91| pdfheadfootsize | _HEADFOOTSIZE | | 12 | Sets the size of the header and footer text in points (1 point = 1/72nd inch) | 
     92| pdfbodyimage | _BODYIMAGE | | http://my.server.com/path/to/background.jpeg | The image that will appear tiled in the background of every page | 
     93| pdflogoimage | _LOGOIMAGE | | http://my.server.com/path/to/logo.jpeg | The logo that will appear in a header or footer if you specify 'l' in the string (see http://www.htmldoc.org) | 
     94| pdfnumberedtoc | _NUMBEREDTOC | | True | Option flag for getting numbered headings and Table of Contents. Set it to anything for true. | 
     95| pdfduplex | _DUPLEX | | True | Option flag to set up the document for duplex printing. Headers and footers will swap position on alternating pages. Set it to anything for true. | 
     96| pdfpermissions | _PERMISSIONS | | print,no-copy | PDF Security permissions to disable print/copy etc. By default the PDF is not protected. | 
     97| pdfmargins | _MARGINS | | top:0.5in,<br />bottom:2.5cm,<br />left:12pt,<br />right:15mm | Specify the page margins (white space to edge of page) | 
     98| pdfbodycolor | _BODYCOLOR | | #CCff99 | Specify the background colour of all pages | 
     99| pdfstruct | _STRUCT | book | webpage | use =book= for structured topics, i.e. when rendering a bunch of topics recursively; use =webpage= when printing a topic without a specific heading structure, i.e. if it is just a normal webpage or if it has got a special VIEW_TEMPLATE | 
     100| pdfcopyright | _COPYRIGHT | %%NOP%WEBCOPYRIGHT% | Copyright 2009 | Should PDF Metadata include the Foswiki %%NOP%WEBCOPYRIGHT% or another value. If set to 0, copyright is excluded. If set to any other string, the string is included in the metadata. Htmldoc has a bug and appends the copyright to the author metadata, which can break some document management systems that depend on the metadata. Set to =0= to exclude the copyright from the PDF metadata. | 
     101| pdfdebug | _DEBUG | 0 | 1 | Include debug messages and don't clean up temporary files after execution | 
     102| pdffirstpage | _FIRSTPAGE | toc | | First page viewer will open: =toc= table of contents; =p1= first page; =c1= first chapter. | 
     103| pdfdestination | _DESTINATION | view | | Output to browser window or save-as prompt | 
     104| pdfpagelayout | _PAGELAYOUT | single | | View's initial presentation layout: =single=, =one=, =twoleft=, =tworight= | 
     105| pdfpagemode | _PAGEMODE | outline | | Viewer's initial presentation mode: =outline=, =document=, =fullscreen= | 
     106| pdfcompress | _COMPRESS | | 9 | Set compression level of the document. 1=minimum, 9=maximum, =none= to disable compression | 
     107| pdfjpegquality | _JPEGQUALITY | | 80 | Set JPEG image quality. Lower quality is higher compression. Set to =none= to disable JPEG image compression | 
     108</small> 
    97109 
    98110If using Foswiki preference variables, copy them to the appropriate web preferences page. This plugin does not read settings from this topic! 
    99111 
    100 %SEARCH{"\|\ [G]ENPDFADDON_" topic="%TOPIC%" type="regex" casesensitive="on" limit="21" nosearch="on" nosummary="on" header="   * Settings for the %SYSTEMWEB%.%TOPIC% Plugin" nototal="on" multiple="on" format="      * #Set $pattern(.*(G.*?N_.*? ).*) = "}% 
     112%SEARCH{"\|\ [_]" topic="%TOPIC%" type="regex" casesensitive="on" limit="21" nosearch="on" nosummary="on" header="   * Settings for the %SYSTEMWEB%.%TOPIC% Plugin" nototal="on" multiple="on" format="      * #Set GENPDFADDON$pattern(.*(_.*? ).*) = "}% 
    101113 
    102114---+++ Limiting the PDF Generation Region 
    … …  
    195207   * %X% This version moves the GenPDFAddOn examples and demo topics from the %System web to the Sandbox web. Old versions of these topics can be removed %from the System web after the upgrade. 
    196208   * The hard-coded =pdftoclevel=0= in the =view.genpdf.tmpl= file has been removed. An alternative approach is to set =GENPDFADDON_TOCLEVELS=0= in Main.SitePreferences 
    197    * This version ships with a !GenPDF Plugin.  This is a helper plugin which will expand the %<nop>GENPDF% tag, and does not need to be enabled. See GenPDFPlugin for more information 
     209   * This version ships with a !GenPDFPlugin.  This is a helper plugin which will expand the %<nop>GENPDF% tag, and does not need to be enabled. See GenPDFPlugin for more information 
     210   * This version renames =lib/Foswiki/Contrib/GenPDF.pm= to =lib/Foswiki/Contrib/GenPDFAddOn.pm=  A shim version of =GenPDF.pm is shipped so that existing configurations will still work without requiring any configuration changes to =lib/LocalSite.cfg= 
    198211 
    199212---+++ Standard installation 
    … …  
    300313|  Dependencies: | %$DEPENDENCIES% | 
    301314 
    302 __Related Topics:__ Sandbox.GenPDFAddOnDemo, Sandbox.GenPDFExampleHeaderFooterTopic, Sandbox.GenPDFExampleTitleTopic, Sandbox.GenPDFAddOnDemoForm, Sandbox.GenPDFAddOnDemoChild, Sandbox.GenPDFAddOnDemoChild2 <!-- PDFSTOP --> 
     315__Related Topics:__  Sandbox.GenPDFAddOnDemo, Sandbox.GenPDFExampleHeaderFooterTopic, Sandbox.GenPDFExampleTitleTopic, Sandbox.GenPDFAddOnDemoChild  Sandbox.GenPDFAddOnDemoChild2 Sandbox.GenPDFAddOnDemoForm 
     316<!-- PDFSTOP --> 
     317 
    303318 
    304319-- TWiki:Main/WadeTurland - 28 Jun 2005%BR% -- TWiki:Main/BrianSpinar - 12 Apr 2005 
Note: See TracChangeset for help on using the changeset viewer.