Quark XPress Server 2017 User Guide QXPS EN
User Manual: quark QuarkXPress Server - 2017 - User Guide Free User Guide for QuarkXPress Software, Manual
Open the PDF directly: View PDF 
.
Page Count: 444
| Download | |
| Open PDF In Browser | View PDF |
A Guide to QuarkXPress Server 2017 Contents Conventions .................................................................................1 Getting started with QuarkXPress Server ...................................3 QuarkXPress Server architecture......................................................................3 Understanding QuarkXPress Server .................................................................3 Server templates and static projects.........................................................................4 The document pool and the Streaming Document Provider....................................4 Projects and layouts ..................................................................................................5 Job Jackets and resources ........................................................................................5 Caching .....................................................................................................................5 QuarkXPress Server preferences...............................................................................6 Quark License Administrator.....................................................................................6 Master-renderer environment ...................................................................................6 Changing logging levels in “log4j2.xml“..................................................................7 Understanding QuarkXPress Server XTensions software .................................8 The QuarkXPress Server XTensions API ....................................................................8 Configuring QuarkXPress Server for launch .....................................................9 Launching QuarkXPress Server.......................................................................10 Quitting QuarkXPress Server .........................................................................10 The QuarkXPress Server user interface .....................................11 Navigation pane..............................................................................................12 Administration menu.......................................................................................17 General Preferences dialog box .............................................................................18 Renderer Preferences dialog box............................................................................20 Job Jackets dialog box ...........................................................................................29 App Studio preferences ..........................................................................................29 Check Out License dialog box................................................................................29 Using QuarkXPress Server .........................................................30 Creating URL requests ....................................................................................30 Understanding URL requests ..................................................................................30 Understanding QuarkXPress Server namespaces ...................................................31 Understanding QuarkXPress Server parameters.....................................................32 Supported interfaces ......................................................................................32 The Dynamic Publishing Process (DPP) ...........................................................33 A GUIDE TO QUARKXPRESS SERVER 2017 | I Getting started ...............................................................................................33 Getting started: HTTP and HTTPS ..........................................................................33 Getting started: Web services.................................................................................39 QXP Server Manager ..............................................................................................49 Using the Web interface .................................................................................50 Understanding rendering........................................................................................50 Understanding logging ...........................................................................................51 Understanding render types ...................................................................................52 Understanding render modifiers .............................................................................87 Using content modifiers..........................................................................................96 Using XML modify.................................................................................................104 Using XML deconstruct and construct ..................................................................120 Working with indexes............................................................................................162 Working with cross references ..............................................................................164 Creating and using hyperlinks ..............................................................................165 Using the Streaming Document Provider .............................................................166 Using administrative request handlers..................................................................167 Using the QXPSM SDK .................................................................................188 Writing a Java QXPSM client ................................................................................188 Writing a .NET QXPSM client ...............................................................................190 Writing an Objective-C client for Mac OS or iOS .................................................192 Extending QuarkXPress Server Manager ..............................................................195 Sample applications ......................................................................................201 Sample applications: QXP Server Manager ..........................................................201 Sample applications legal notice ..........................................................................202 QuarkXPress Server Features ..................................................211 Dynamic Pagination and Flow.......................................................................211 Dynamic Pagination and Flow Problem ................................................................212 Dynamic Pagination and Flow Solution ................................................................213 Landscape pagination ...................................................................................216 Automatic callout stacking............................................................................220 Automatic callout stacking example .....................................................................221 Nested anchoring..........................................................................................222 Nested anchoring examples .................................................................................222 Modifier schema (annotated) ...................................................225 Entities (Modifier DTD) .................................................................................225 ADDCELLS (Modifier schema).......................................................................226 ALIGNHORSETTINGS (Modifier schema)......................................................226 ALIGNVERSETTINGS (Modifier schema).......................................................227 ALLOWBOXOFFPAGE (Modifier schema).....................................................228 ALLOWBOXONTOPASTEBOARD (Modifier schema)....................................228 ANCHOREDBOXREF (Modifier schema).......................................................228 ARTICLE (Modifier schema)...........................................................................230 ii | A Guide to QuarkXPress Server 2017 AUTHOR (Modifier schema) ..........................................................................230 BNSTYLE (Modifier schema) .........................................................................231 BOTTOM (Modifier schema) .........................................................................231 BOTTOMGRID (Modifier schema) .................................................................231 BOX (Modifier schema) .................................................................................233 BOXATTRIBUTE (Modifier schema) ...............................................................236 BOXREF (Modifier schema)...........................................................................238 CALLOUTANCHOR (Modifier schema)..........................................................239 CALLOUTBOXREF (Modifier schema) ...........................................................240 CELL (Modifier schema) ................................................................................240 CHILDID (Modifier schema)...........................................................................243 CLIPPING (Modifier schema).........................................................................243 COLGROUP (Modifier schema) .....................................................................246 COLSPEC (Modifier schema) .........................................................................246 COLUMN (Modifier schema) .........................................................................247 COLUMNFLOW (Modifier schema) ...............................................................249 COLUMNSPAN (Modifier schema) ................................................................250 COLUMNSPLIT (Modifier schema) ................................................................250 COMPONENT (Modifier schema)..................................................................251 COMPOSITIONZONE (Modifier schema)......................................................253 CONDITIONALMASTERPAGEREFERENCE (Modifier schema) .....................255 CONTENT (Modifier schema)........................................................................256 CONTENTPH (Modifier schema) ...................................................................258 CONTINUEDHEADER (Modifier schema)......................................................259 CONTINUEDTROWSTYLE (Modifier schema) ...............................................259 CONTOUR (Modifier schema) .......................................................................260 CONTOURS (Modifier schema) .....................................................................260 COPYFIT (Modifier schema) ..........................................................................261 COPYRIGHT (Modifier schema).....................................................................261 DATAPROVIDER (Modifier schema) ..............................................................261 DEL (Modifier schema) ..................................................................................262 DELETECELLS (Modifier schema)..................................................................262 DESCRIPTION (Modifier schema)..................................................................262 DROPCAP (Modifier schema)........................................................................263 EBOOKMETADATA (Modifier schema)..........................................................263 ENTRY (Modifier schema) .............................................................................264 EVENTCOLSTYLE (Modifier schema) ............................................................265 EVENTROWSTYLE (Modifier schema)...........................................................266 FIRSTTCOLSTYLE (Modifier schema) ............................................................266 FIT (Modifier schema) ...................................................................................267 FITTEXT (Modifier schema) ...........................................................................268 FOOTER (Modifier schema) ..........................................................................270 FOOTERTROWSTYLE (Modifier schema) ......................................................270 FORMAT (Modifier schema) ..........................................................................270 A Guide to QuarkXPress Server 2017 | iii FRAME (Modifier schema) ............................................................................273 GEOMETRY (Modifier schema) .....................................................................275 GRID (Modifier schema) ................................................................................277 GRIDLINE (Modifier schema) ........................................................................278 GROUP (Modifier schema) ............................................................................281 GROUPCHARACTERS (Modifier schema)......................................................282 GROWACROSS (Modifier schema)................................................................283 GROWDOWN (Modifier schema)..................................................................283 HEADER (Modifier schema) ..........................................................................283 HEADTROWSTYLE (Modifier schema) ..........................................................283 HEIGHT(Modifier schema).............................................................................284 HIDDEN (Modifier schema)...........................................................................284 HYPERLINK (Modifier schema) .....................................................................286 ID (Modifier schema).....................................................................................287 INDEXTERM (Modifier schema) ....................................................................288 INLINEBOX (Modifier schema) .....................................................................289 INLINETABLE (Modifier schema)...................................................................293 INS (Modifier schema)...................................................................................294 INSET (Modifier schema)...............................................................................294 INTERACTIVITY (Modifier schema) ...............................................................295 ISBN (Modifier schema) ................................................................................295 KEEPLINESTOGETHER (Modifier schema)....................................................295 KEYWORDS (Modifier schema).....................................................................296 LASTTCOLSTYLE (Modifier schema) .............................................................296 LAYER (Modifier schema)..............................................................................297 LAYOUT (Modifier schema) ...........................................................................298 LAYOUTREF (Modifier schema).....................................................................300 LEFT (Modifier schema) ................................................................................301 LEFTCONTROLPOINT (Modifier schema) .....................................................301 LEFTGRID (Modifier schema) ........................................................................301 LINESTYLE (Modifier schema).......................................................................303 LINKEDBOX (Modifier schema) ....................................................................304 LIST (Modifier schema)..................................................................................305 LOCATION (Modifier schema).......................................................................305 LOCKTOGRID (Modifier schema) ..................................................................306 MASTERPAGESEQUENCE (Modifier schema)...............................................306 MATHEQUATION (Modifier schema) ............................................................307 MAX (Modifier schema) ................................................................................307 METADATA (Modifier schema) ......................................................................307 MIN (Modifier schema) .................................................................................308 MOVEDOWN (Modifier schema) ..................................................................308 MOVELEFT (Modifier schema) ......................................................................308 MOVERIGHT (Modifier schema)....................................................................308 MOVEUP (Modifier schema) .........................................................................308 iv | A Guide to QuarkXPress Server 2017 NOTE (Modifier schema)...............................................................................309 ODDTROWSTYLE (Modifier schema) ............................................................309 ODDTCOLSTYLE (Modifier schema)..............................................................310 ORIGIN (Modifier schema) ............................................................................310 OVERMATTER (Modifier schema) .................................................................310 PAGE (Modifier schema) ...............................................................................311 PAGEBREAK (Modifier schema)....................................................................312 PAGEREF (Modifier schema) .........................................................................313 PAGESEQUENCE (Modifier schema) ............................................................313 PARAGRAPH (Modifier schema) ...................................................................314 PARENTTABLE (Modifier schema).................................................................316 PICTURE (Modifier schema) ..........................................................................316 PLACEHOLDER (Modifier schema) ...............................................................321 POSITION (Modifier schema) ........................................................................321 PROJECT (Modifier schema) .........................................................................321 PUBLICATION (Modifier schema)..................................................................322 PUBLICATIONCHANNEL (Modifier schema) .................................................323 PUBLISHER (Modifier schema) ......................................................................323 REFNOTE (Modifier schema) ........................................................................323 RELPOSITION (Modifier schema)..................................................................324 REPEATABLEMASTERPAGEALTERNATIVES (Modifier schema)....................324 REPEATABLEMASTERPAGEREFERENCE (Modifier Schema) ........................325 RGBCOLOR (Modifier schema) .....................................................................325 RICHTEXT (Modifier schema)........................................................................326 RIGHT (Modifier schema) ..............................................................................348 RIGHTCONTROLPOINT (Modifier schema)...................................................348 RIGHTGRID (Modifier schema)......................................................................349 ROW (Modifier schema) ................................................................................351 RUBI (Modifier schema) ................................................................................355 RUBITEXT (Modifier schema) ........................................................................356 RULE (Modifier schema)................................................................................358 RUNAROUND (Modifier schema)..................................................................360 SAVEAS (Modifier schema) ...........................................................................364 SCALETO (Modifier schema) .........................................................................365 SECTION (Modifier schema) .........................................................................366 SECTIONNUMBERFORMAT (Modifier schema) ............................................366 SHADINGSTYLE (Modifier schema) ..............................................................366 SHADOW (Modifier schema).........................................................................368 SHRINKACROSS (Modifier schema)..............................................................374 SHRINKDOWN (Modifier schema) ................................................................374 SINGLEMASTERPAGEREFERENCE (Modifier schema) .................................375 SIZE (Modifier schema) .................................................................................375 SPINEIMAGE (Modifier schema) ...................................................................375 SPLINESHAPE (Modifier schema) .................................................................376 A Guide to QuarkXPress Server 2017 | v SPREAD (Modifier schema) ...........................................................................377 STACKINGORDER (Modifier schema) ...........................................................377 STATICCONTENT (Modifier schema).............................................................377 STORY (Modifier schema) .............................................................................377 SUPPRESSOUTPUT (Modifier schema)..........................................................379 TAB (Modifier schema) ..................................................................................379 TABLE (Modifier schema) ..............................................................................380 TABLEBREAK (Modifier schema)...................................................................383 TABLESTYLE (Modifier schema) ....................................................................383 TABSPEC (Modifier schema)..........................................................................384 TBODY (Modifier schema).............................................................................384 TCOL (Modifier schema) ...............................................................................384 TCOLSTYLE (Modifier schema) .....................................................................385 TCONTINUED (Modifier schema)..................................................................386 TEXT (Modifier schema) ................................................................................386 TEXTATTRIBUTE (Modifier schema) ..............................................................390 TEXTNODEPH (Modifier schema) .................................................................390 TEXTPH (Modifier schema) ...........................................................................391 TFOOT (Modifier schema) .............................................................................392 THEAD (Modifier schema).............................................................................392 TITLE (Modifier schema)................................................................................392 TOP (Modifier schema) .................................................................................392 TOPGRID (Modifier schema) .........................................................................393 TROW (Modifier schema) ..............................................................................394 TROWSTYLE (Modifier schema) ....................................................................395 VALUE (Modifier schema) .............................................................................396 VERTEX (Modifier schema) ...........................................................................396 VERTEXPOINT (Modifier schema).................................................................397 VERTICES (Modifier schema) ........................................................................397 WIDTH (Modifier schema) .............................................................................398 XREF (Modifier schema)................................................................................398 Using SSL..................................................................................399 Secure Sockets Layer (SSL) support..............................................................399 Enabling SSL .........................................................................................................399 Enabling HTTP and HTTPS ...................................................................................400 Verifying and using SSL.........................................................................................400 Keystores and SSL certificates ..............................................................................400 QuarkXPress Server XTensions software .................................401 CopyDeskArticle XTensions software ...........................................................401 Rendering articles .................................................................................................401 Exporting articles ..................................................................................................401 Adding articles to projects....................................................................................402 Creating and deleting components ......................................................................402 vi | A Guide to QuarkXPress Server 2017 PDF Filter XTensions software......................................................................403 Modifier XTensions software ........................................................................403 Using Modifier XTensions software .......................................................................404 Creating XML for Modifier XTensions software.....................................................404 Layer XTensions software .............................................................................405 InteractiveDesigner Server XTensions software ...........................................405 App Studio XTensions software ....................................................................406 Telegraph XTensions software..................................................407 Setting Telegraph preferences......................................................................407 Specifying a server for template upload...............................................................408 Using Telegraph XTensions software ............................................................409 Identifying QuarkXPress items and groups...........................................................409 Naming items and groups ....................................................................................410 Uploading templates ............................................................................................410 Uploading missing or modified pictures...............................................................412 QuarkXPress Server Manager..................................................413 Understanding QuarkXPress Server Manager ..............................................413 Load balancing .....................................................................................................413 Request timeout interval.......................................................................................414 Determining QuarkXPress Server instance availability..........................................415 Logging with QXP Server Manager ......................................................................415 Caching .................................................................................................................415 Web services .........................................................................................................416 Working with QuarkXPress Server Manager ................................................416 Starting QuarkXPress Server Manager..................................................................416 Request handler binding.......................................................................................418 Configuring QuarkXPress Server instances...........................................................418 Managing the cache .............................................................................................422 Managing logs ......................................................................................................424 Using a proxy server..............................................................................................427 Generating automatic e-mail messages ...............................................................427 Using other global settings...................................................................................428 Saving a server configuration................................................................................430 Using custom error messages ...............................................................................430 Sending requests from a browser .........................................................................431 The XTensions Developer Kit (XDK).........................................434 Glossary ...................................................................................435 Legal notices ............................................................................436 A Guide to QuarkXPress Server 2017 | vii CONVENTIONS Conventions Formatting conventions highlight information to help you quickly find what you need. • Bold type style: The names of all dialog boxes, fields, and other controls are set in bold type. For example: “Click OK.” • References: In descriptions of features, parenthetical references guide you in accessing those features. For example: “The Find/Change dialog box (Edit menu) lets you find and replace text.” • Arrows: You will often see arrows (>), which map out the menu path to a feature. For example: “Choose Edit > Style Sheets to display the Style Sheets dialog box.” • Icons: Although many tools and buttons are referenced by name, which you can see by displaying ToolTips, in some cases icons are shown for easy identification. For example, “Click the • button on the Measurements palette to center text.” Cross-platform issues: This application is quite consistent across operating systems. However, some labels, buttons, key combinations, and other aspects of the application must differ between Mac OS® and Windows® because of user interface conventions or other factors. In such cases, both the Mac OS and Windows versions are presented, separated by a slash, with the Mac OS version presented first. For example, if the Mac OS version of a button is labeled Select, and the Windows version is labeled Browse, you are directed to “Click Select/Browse.” More complex cross-platform differences are mentioned in notes or parenthetical statements. A GUIDE TO QUARKXPRESS SERVER 2017 | 1 CONVENTIONS 2 | A Guide to QuarkXPress Server 2017 GETTING STARTED WITH QUARKXPRESS SERVER Getting started with QuarkXPress Server QuarkXPress Server lets you render QuarkXPress projects in a variety of formats. QuarkXPress Server architecture The QuarkXPress Server architecture is shown in the following diagram. QuarkXPress Server architecture diagram Understanding QuarkXPress Server QuarkXPress Server helps automate the generation of QuarkXPress layouts to a variety of output formats—including JPEG, Portable Document Format (PDF), and PostScript®—all from a centralized Web application. To send a request to QuarkXPress Server, all you need to do is enter a URL into your Web browser’s A GUIDE TO QUARKXPRESS SERVER 2017 | 3 GETTING STARTED WITH QUARKXPRESS SERVER address field. For example, the following URL instructs the QuarkXPress Server application named “QXPServer” to return the file “MyProject.qxp” as a PDF file: http://QXPServer:8080/pdf/MyProject.qxp The QuarkXPress Server application receives these requests, renders (creates) the requested projects in the requested formats, and then returns the rendered file to the client application—the Web browser in this case. The format of QuarkXPress Server URL requests is described in detail in “Creating URL requests“ and in “Web integration.” You can also create custom applications that communicate with a QuarkXPress Server application using HTTP, Simple Object Access Protocol (SOAP), or another protocol. For more information, see “Web integration.” You can think of QuarkXPress Server as a special version of QuarkXPress that runs on a server with the following main differences: • Instead of accepting input from a keyboard and mouse, QuarkXPress Server accepts input in the form of URLs and other types of requests. • Instead of sending a project to a printer, QuarkXPress Server renders (creates) output in a particular format and sends the rendered file to a client. Server templates and static projects QuarkXPress Server can open, render, and serve two types of projects: • Static projects are QuarkXPress projects that can be rendered and served as-is in a variety of formats by the QuarkXPress Server application. For example, you might make a product manual available as a static project and allow customers to download that manual in a variety of formats. • Server templates are QuarkXPress projects that can be manipulated by the QuarkXPress Server application before being rendered and served. For example, you might make a sales piece available as a server template so that each person who downloads it receives a personalized copy. QuarkXPress Server can open QuarkXPress documents, projects, and templates created in any language edition of QuarkXPress 7.0 or later. QuarkXPress Server can save and export projects in QuarkXPress 8.x, 9.x and 10.x format. The document pool and the Streaming Document Provider QuarkXPress Server has two main ways to find or receive content for rendering. • The document pool • The Streaming Document Provider QuarkXPress Server can read templates and static projects from a directory called the document pool. The document pool can be any directory that is available to QuarkXPress Server through a file system or an FTP server. You can use any of the following methods to place files in the document pool: • Drag the files to the document pool directory. 4 | A Guide to QuarkXPress Server 2017 GETTING STARTED WITH QUARKXPRESS SERVER • Use the Add Files command in the Document Pool screen of the QuarkXPress Server Web interface. • Upload the files using FTP to the document pool directory. • Use Telegraph XTensions® software to upload the files to the document pool from within QuarkXPress. (For more information about Telegraph XTensions software, see “Telegraph XTensions software.”) For more information about the document pool, see “The QuarkXPress Server User Interface.” The document pool directory cannot be an encrypted directory. QuarkXPress Server can also receive templates, projects, and other files as part of a multipart HTTP request. For more information, see “Using the Streaming Document Provider.” In addition, QuarkXPress Server can serve documents from a database, a content management system, or other sources. Collectively, the document pool and any other source of files to be served are referred to as document providers. Projects and layouts QuarkXPress projects can contain one or more layouts, and only one layout can be rendered at any given time. If you do not specify a layout when you send a rendering request, QuarkXPress Server renders the first layout in the project. Job Jackets and resources In QuarkXPress, resources are things such as style sheets, colors, H&Js, output styles, and item styles. Resources are stored in a Job Jackets structure, which can be either embedded in a project or stored in a separate Job Jackets file. QuarkXPress Server uses a default Job Jackets file to make a default set of resources available to all projects handled by QuarkXPress Server, regardless of whether they are included in the projects and articles you render. You can update this file in two ways: • Using the QuarkXPress Server Web interface. For more information, see “Job Jackets dialog box.” • Using request handlers. For more information, see “jobjacket“ and “updateprefsfromjj.” Once you’ve downloaded the default Job Jackets file, you can update its resources using QuarkXPress. For more information, see “Job Jackets” in A Guide to QuarkXPress. The location of the default Job Jackets file is stored in the QuarkXPress Server preferences folder. For more information, see “QuarkXPress Server preferences.” Caching To maximize efficiency, QuarkXPress Server uses cached versions of all rendered projects whenever possible. You can configure projects so that they are never A Guide to QuarkXPress Server 2017 | 5 GETTING STARTED WITH QUARKXPRESS SERVER cached, so that they are cached for a particular amount of time, or so that they are rendered every time they are served. QuarkXPress Server preferences When you launch QuarkXPress Server, the application creates preferences files that are functionally and structurally equivalent to the preferences files created by QuarkXPress. These preferences files reside in the QuarkXPress Server “Preferences” folder. QuarkXPress Server also creates a “QuarkXPress Server.prf” file in the “Preferences” folder. This file contains preference settings that are specific to QuarkXPress Server. QuarkXPress Server uses these preferences the same way QuarkXPress uses them. If an XTensions module creates a project in QuarkXPress Server, that project draws its settings from the QuarkXPress Server preferences just as a new QuarkXPress project draws its settings from the QuarkXPress preferences. Preferences files are stored in the following locations: • Mac OS: [User]/Library/Preferences/Quark/QuarkXPress Server Renderer/ • • • • Windows : C:\Windows\System32|config\systemprofile\AppData\Roaming\Quark \QuarkXPressServer Renderer [version] For more information about preferences, see the “Administration menu.” Quark License Administrator To prevent unauthorized use, launching QuarkXPress Server requires the presence of a Quark® License Administrator (QLA) server. QuarkXPress Server follows the configuration and control rules that are enforced by QLA. For more information about QLA, see the QLA documentation included with QuarkXPress Server. Master-renderer environment Requests for project renders are stored in a connection queue. The requests in the rendering queue can be processed by a single QuarkXPress Server application, or by a master QuarkXPress Server application and several renderers (additional instances of QuarkXPress Server). The master QuarkXPress Server application launches the available number of renderers and then passes the requests in the connection queue to those renderers as they become available. The number of renderers available for launch is determined by the number of licenses available from the QLA server. The master QuarkXPress Server process and all of the renderers it launches share the following elements: 6 | A Guide to QuarkXPress Server 2017 GETTING STARTED WITH QUARKXPRESS SERVER • The same application preferences (each renderer has its own preferences files, but QuarkXPress Server keeps them synchronized) • The same document cache in memory • The same memory cache • The same server XTensions modules (a separate instance of each XTensions module runs with each renderer) • The same server document pool (if defined in the QuarkXPress Server preferences or if a document provider is used in place of the document pool) If a renderer unexpectedly quits, the master QuarkXPress Server restarts the renderer without requiring any action from you. Changing logging levels in “log4j2.xml“ You can change the logging levels for QuarkXPress Server. Options include ERROR, INFO, WARN, DEBUG, and TRACE. • ERROR = includes messages that indicate disrupted and failed requests. • INFO = includes messages that indicate the state of services. • DEBUG = includes messages that indicate server resource usage. • • WARN = includes non-critical service error messages TRACE = includes messages according to activity related to requests. Refer to Java documentation for more information about logging levels. To change logging levels: 1. Open the “conf” folder in your QuarkXPress Server folder. 2. Open “log4j2.xml” in a text-editing application. 3. name=com.quark.qxps. The structure is as follows: 4. 5. To define the logging level for QuarkXPerss Server errors, scroll toTo define the logging level for QuarkXPress Server transactions, scroll to To define the logging level for other activity, scroll to the . The structure is as follows: 6. Save and close “log4j2.xml.” A Guide to QuarkXPress Server 2017 | 7 GETTING STARTED WITH QUARKXPRESS SERVER Understanding QuarkXPress Server XTensions software QuarkXPress Server ships with a collection of XTensions software that adds capabilities to QuarkXPress Server. For example, PDF Export XTensions software lets QuarkXPress Server serve content in PDF format; Modifier XTensions software lets you retrieve, manipulate, and reconstruct XML representations of projects; and QuarkCopyDesk® Renderer XTensions software lets you create QuarkCopyDesk articles. Telegraph XTensions software works with QuarkXPress to allow designers to name boxes in template files so that those boxes can be addressed by URLs. For more information about XTensions software included with QuarkXPress Server, see “XTensions software“ and “Telegraph XTensions software.” The QuarkXPress Server XTensions API In addition to the XTensions modules included with QuarkXPress Server, developers can create custom XTensions software that add features. The complete server XTensions Application Programming Interface (API) documentation is available in the QuarkXPress Server XTensions Developer’s Kit (XDK). As of version 8.0, the QuarkXPress Server XDK is Unicode-compliant. The QuarkXPress Server XDK lets you create XTensions modules that provide the following abilities: • The ability to register request handlers • The ability to register project providers • The ability to register new render formats • The ability to add items to the list of response properties, cookies, and HTTP header items • The ability to log messages in log files • The ability to initiate a new transaction to be processed by the server • The ability to completely control how projects are processed by the server In addition, QuarkXPress Server XTensions software can register for the following basic callbacks: • Pre-processing • Content loading • Layout modification • Post-processing • Removing slugs while running the QuarkXPress project renderer • Analyzing the server after a transaction is complete • Pre- and post-transaction callback 8 | A Guide to QuarkXPress Server 2017 GETTING STARTED WITH QUARKXPRESS SERVER Configuring QuarkXPress Server for launch To configure QuarkXPress Server prior to launch, open the file [QuarkXPress Server application folder]/conf/ServerApp.properties folder) and modify it as follows: • To make the server run without loading any network interface, use the - nonetwork option with the qxpservercore.serverRendererParameters. In this mode, the only transactions a server can run are those passed to it by another process. • To control whether renderers are monitored, set qxpservercore.monitorrenderers.value to true or false. • To specify the query interval for monitoring renderers, set qxpservercore.monitorrenderers.queryinterval.value to a value in seconds. • To specify the number of retries for monitoring renderers, set qxpservercore.monitorrenderers.noofretries.value to an integer. If a renderer process has been attempting to fulfill a request for the specified number of retries (with the specified query interval in seconds between retries), the renderer monitor recyles that process. • To control how many renderers the master process launches, specify a number for qxpserver.subrenders. Note that the number of renderers you can launch depends on your license. • To force the renderers to restart on a periodic basis, specify a value in hours for qxps.render.recycle.interval. The default value is 24, or 24 hours. Decimal values are permitted. Renderers restart serially, so one renderer doesn’t restart until the other is finished restarting. If a renderer is busy, the master process waits for 15 minutes, and then if the renderer is still busy, postpones the restart until the next interval elapses. Set this value to zero to turn the automatic restart feature off. • The request timeout at Renderer lets you specify the timeout value for rendering. It is set to 10 minutes by default. qxpserver.renderer.request.timeout.name = requestTimeout qxpserver.renderer.request.timeout.value = 10 • To control whether the server should collect performance metrics, set qxpserver.CollectPerformanceMetrics=true to collect and false to not collect metrics. • To set the number to transactions after which performance metrics data will be flushed to file: qxpserver.CollectPerformanceMetrics.flush.transactioncount = 100 • To send JMX notifications when performance metrics change set: qxpserver.CollectPerformanceMetrics.sendjmxnotifications = true • Enable this flag to automatically refresh admin ui through JMX notifications qxpserver.CollectPerformanceMetrics.adminui.autorefresh = true A Guide to QuarkXPress Server 2017 | 9 GETTING STARTED WITH QUARKXPRESS SERVER • To reset metrics on every launch of qxps. If set to true, the QuarkXPress Server will clear old metrics and start capturing fresh metrics on every launch. qxpserver.CollectPerformanceMetrics.resetmetricsonserverlaunch = false • To accelerate the time to troubleshoot a failed rendering request, QuarkXPress Server creates the rescue folder and collects the data for failed and timed out transactions by default into a folder name QXPSRescuedata relative to doc pool. Setting this value to false means the rescue folder will not be created and no data will be collected. qxpserver.rescuefolder.manage=true • Specify the rescue folder path for failed transactions. If no value is given here, the document pool path would be considered by default: qxpserver.rescuefolder.path = Launching QuarkXPress Server On Windows, you can install QuarkXPress Server as an application or as a service (Quark recommends that you always run it as a service). On Mac OS, QuarkXPress Server always runs as an application. If you install QuarkXPress Server on Windows as an application, you can launch it using the Start menu or by double-clicking the “ServerStartup.bat” in the QuarkXPress Server application folder. For information on launching QuarkXPress Server in a separate Tomcat installation, see “Deploying QuarkXPress Server externally” in the QuarkXPress Server ReadMe. QuarkXPress Server offers a browser-based user interface instead of a conventional user interface. Quitting QuarkXPress Server To quit QuarkXPress Server, press Control+C. 10 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE The QuarkXPress Server user interface QuarkXPress Server offers a browser-based user interface. This chapter describes how you can use it to configure and customize your QuarkXPress Server application and manage your server XTensions modules. To view the QuarkXPress Server welcome page, launch a Web browser and enter the URL http://[server]:[port] (where [server] is the IP address or domain name of the server and [port] is the TCP/IP port on which the server is running). The welcome screen displays. The QuarkXPress Server welcome page To display the administrative client, click Open Admin Client. If the server has realm verification enabled, you will be asked to enter your user name and password. The administrative client displays. A GUIDE TO QUARKXPRESS SERVER 2017 | 11 THE QUARKXPRESS SERVER USER INTERFACE Navigation pane Status Monitor screen The navigation pane on the left side has two areas shown in the lower left. The Server Information area lets you view server information and the transaction log, and the Document Pool area lets you view the contents of the document pool. You can collapse and expand this pane with the button at the right end of the Navigation Pane header. If you click Server Information, the Status Monitor screen displays. This screen shows the following usage reporting metrics : 1. Server Name: Name or IP of the machine running QuarkXPress Server. 2. Server Startup time: Shows the date and time at which the QuarkXPress Server Service was launched. 3. Active Renderers: Represents the number of renderers busy processing a rendering job. This updates dynamically. 4. Idle Renderers: Represents the number of renderers in an idle state. This updates dynamically. 5. Observation Time: The time period during which the server’s activity is monitored to collect performance metrics. 6. Busy Time: Sum of all time periods when the server is busy processing at least one rendering transaction. For Example: Busy Time = Busy Period 1 + Busy Period 2 + Busy Period 3 + … + Busy Period n, where Tr1, Tr2, …Trn represent incoming rendering transactions. 12 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE Busy Time : Transactions Vs. Observation Period 7. Server Utilization: The percentage of server capacity used during the Observation Time. Utilization (%) = (Busy Time /Observation Time) * 100. For Example: For an Observation Time of 50 minutes if the server is busy for 40 minutes, the Server Utilization(%) = (40 / 50) * 100 = 80%. 8. Rendering Throughput: The average number of rendering transactions completed during Busy Time. Rendering Throughput = total rendering transactions completed / Busy Time. For example, if 150 rendering transactions are completed in a busy time of 50 minutes, then the throughput would be 150/50 = 3 transactions / min. 9. Arrival Rate: The number of arrivals per unit of time. Arrival Rate = Total transactions arrived / Observation Time For example for a total of 1500 rendering requests arrived, during 50 minutes Observation Time, the Arrival Rate = 1500/50 = 30 transactions / minute. 10. Response Time for a rendering transaction: It is the total time taken to complete a transaction from its submission to completion. Response Time= Queue Time + Processing Time For example if a server running with 2 the rendering transaction Tr1 goes to renderer1, Tr2 goes to renderer2, Tr3 waits in queue until one of the renderer becomes free. The response time for each rendering transaction is as shown below. A Guide to QuarkXPress Server 2017 | 13 THE QUARKXPRESS SERVER USER INTERFACE Response Time: Transactions Vs. Time 11. Average Response Time: Average amount of time taken to complete a transaction from its submission to completion. For Example: Time taken to complete transaction 1 = Tr1 Time taken to complete transaction 2 = Tr2 … … Time taken to complete transaction n = Trn Average Response Time = (Tr1 + Tr2 + … + Trn) / n 12. Peak Response Time: The highest response times recorded during a given observation time. For example, if during a given Observation Time, if response times for various rendering transactions are as below, Tr1 = 7 sec Tr2 = 15 sec Tr3 = 2 sec Tr4 = 2 sec Tr5 = 20 sec … … Trn = 4 sec Peak Response Time = MAX(7,15,2,2,20 …4) = 20 sec. 14 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE 13. Average Queue Time: The average time a rendering job stays in the queue before it gets processed. The average queue time = total queue time / total rendering transactions completed. For example, if the total queue time is 3 minutes (i.e. 180 seconds) and 150 transactions are completed, then the Average Queue Time = (3 * 60) /150 = 1.2 seconds 14. Peak Queue Time: The highest waiting time a rendering job stays in the queue. For example, if during a given Observation Time, the waiting times iare: Tr1 = 0 sec Tr2 = 5 sec Tr3 = 2 sec … … Trn = 4 sec Peak Queue Time = MAX(0,5,2, …4) = 5 sec. 15. Current Queue Length: The number of rendering jobs waiting in the queue to be processed. 16. Peak Queue Length: The highest queue lengths recorded during a given observation time. 17. Rendering Requests: The total number of transactions delegated to renderers during a given observation time (e.g. PDF, JPG, /getprojinfo, /jobjacket, /getrendererprefs, /setrendererprefs, etc). 18. Pages Rendered: Sum total of all pages rendered for each rendering transaction during a busy time. 19. Images Processed: Sum total of all image files either imported or rendered as a part of the rendering transaction during the observation time. 20. Average Rendering Time Per Page: The average time taken to render a page. Average rendering time per page = busy time / total pages rendered. For example, if a total of 15000 pages are rendered when the server was busy for 50 minutes (i.e. 3000 sec), the Average Rendering Time Per Page = (50*60)/15000 = 0.2 seconds 21. Total Renditions: The number of renditions of various formats rendered by the server during the observation time. By default, this includes PDF, JPEG, HTML5, EPUB, KINDLE, APPSTUDIO, EPS, XML, PNG, CopyDesk Articles, QuarkXPress Projects. 22. Failed Transactions Count: The number of failed transactions. 23. Error Rate: The percentage of failed transactions during the Observation Time. For example if out of 500 rendering transactions, if 10 transactions failed, then the Error Rate (%) = (10 / 500) * 100 = 2%. A Guide to QuarkXPress Server 2017 | 15 THE QUARKXPRESS SERVER USER INTERFACE 24. RESET button: Clicking on the reset button results in the following sequence of actions: • The server usage information recorded during the Observation Time is backed up to a backup file (Telemetry.json) within the QuarkXPress Server logs folder. • Clears all the server usage information displayed in the Status Monitor page of Admin UI by resetting the values to zero. • Starts a fresh Observation Time under which all the usage information will be freshly recorded again. The icons in the area below represent the renderers that are currently running and show which requests are being processed by each renderer in real time. This screen also shows the number of active and idle renderers. The information for the Observation Time can be downloaded as a backup (step-5). A file named “Telemetry.json” is downloaded in association with the .zip archive downloaded using the Download Logs button under Manage Logs. REST interface for usage data: http:// :8080/telemetry http:// :8080/cleartelemetry If you click Manage Logs, the Logs screen displays the current transaction log. Logs screen • To download the active log including recent crash reports, click Download Logs at the top of the Logs header. • To make the log scroll automatically as events occur, check Auto Scroll. • To clear all logs, click Clear All Logs. • To clear the current log, click Clear Log. 16 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE • To display the Log Settings dialog box, click Log Settings. In this dialog box, you can change the maximum log file size, the maximum rolling count, and the logging level for the general QuarkXPress Server log, the QuarkXPress Server transaction log, and the QuarkXPress Server fatal log. • Each transaction entry in the QuarkXPress Server transaction log has some useful information related to request URI, time taken for rendering, rendered output size, pages generated, images processed, average time per page, time/duration a transaction has waited in the queue before it got processed(queue time), queue length, and the number of other transactions still waiting in the queue at the time it was processed. • To view a particular log file, choose an option from the Select Log File dropdown menu. If you click Show XTensions Information, the XTensions Information screen displays, allowing you to view the status of all installed XTensions modules. If you click Manage Fonts, a list of fonts installed on the Server machine is displayed. Fonts screen To search fonts, use the list search box in the top right corner. To add fonts to the Server machine, click the Add Fonts button. This will copy the fonts to the “privatefonts” folder in the QuarkXPress Renderer folder. Administration menu The administration menu lets you manage QuarkXPress Server. A Guide to QuarkXPress Server 2017 | 17 THE QUARKXPRESS SERVER USER INTERFACE You do not have to restart the server in GUI mode to set preferences. General Preferences dialog box The General Preferences dialog box (Administration > Preferences > General) lets you set preferences that are not related to rendering. It includes the tabs described in the following topics. You can also set general preferences using the setprefs request handler. For more information, see “setprefs.” General Preferences — Server The Server tab (Administration > Preferences > General > Server) includes the following controls. Use the Document Root Folder field to specify the location of the document pool. Putting the document pool on a network connected drive is not recommended, because this negatively impacts the performance of QuarkXPress Server. Use the Allow Memory Caching check box to control whether memory is cached. Use the Max Memory Cache Size field to specify the maximum memory size allocated to the cache memory. Valid values are from 10MB to 1024MB. Use the Force Served Documents Closed check box to control whether QuarkXPress Server closes projects from the document pool after it renders them, regardless of the Telegraph XTensions software setting. Uncheck this box to keep such projects open on the server. Use the Default Renderer Type drop-down menu to specify the default rendering format for the server. • Appstudio: Returns a .zip file containing an HTML5 App Studio article. • Appstudio Upload: Exports an HTML5 App Studio article and uploads it to the App Studio Publishing Portal. • ePUB: Returns an ePUB file. • EPS Document: Returns an Encapsulated PostScript (EPS) file. • JPEG: Returns a JPEG file. • PDF: Returns a PDF file. • PNG: Returns a Portable Network Graphics (PNG) file. • PostScript: Returns a PostScript file. • QCDDOC: Returns a QuarkCopyDesk article. • QuarkXPress Document: Returns a QuarkXPress project. • Raw Custom: Returns a file in internal QuarkXPress format for use by server XTensions software developers. • RLE Raw Custom: Returns a file in internal QuarkXPress format (compressed using Run Length Encoding) for use by server XTensions software developers. 18 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE Use the Scale field to specify the default scale percentage at which QuarkXPress Server should render projects. Use the Disable QXD Return check box to specify whether QuarkXPress Server can return QuarkXPress projects to clients. General Preferences — Log The Log tab (Administration > Preferences > General > Log) includes the following controls. Use the Log Document Problems check box to specify whether to include problem descriptions in transaction log files. The “Log” folder inside the QuarkXPress Server application folder contains three log files: • • QuarkXPress Server Fatal Log.log: This log lists all fatal errors. QuarkXPress Server Log.log: The log for the Java process. This log contains source code-level logging information that can be useful in troubleshooting. • QuarkXPress Server Transaction Log.log: This log lists all transactions and all errors. Detailed application logging is enabled for these log files only if it is enabled in the “log4j.xml” file. To log detailed transaction timing data, check Log Timing Data. Logged problems include the following: • Missing Fonts: If fonts are missing from a project that has been requested for rendering, a one-line description of each missing font is added to the error log. If QuarkXPress Server receives a request to render a project and does not have access to the fonts required by the project, it uses the fonts specified in the Fonts tab of the Preferences dialog box (Administration > Preferences > General). If these fonts are also unavailable, QuarkXPress Server substitutes Helvetica (Mac OS) or Arial (Windows). This behavior is the same as it is in QuarkXPress. • Missing Pictures • Missing SXTs: If a required server XTensions module is missing when a rendering request is received, a one-line description of each missing module is added to the error log. If the name of the missing module is not returnable, the XTensions module ID number is returned. • Text Encoding/Character Set Problems: If text is sent to a text box in the template and the system does not have access to the correct font glyph, the issue is logged. The log data indicates the character set that the system attempted to convert. For example, the log entry might show that a request for Japanese characters was sent to an English project. Information about missing fonts and missing pictures is also recorded in the “QuarkXPressServerRenderer.log” file. This file also contains detailed timing information, including the transaction UID for each transaction. This log file can be found here: • Mac OS: [drive]/Users/[user name]/Library/Logs/Quark A Guide to QuarkXPress Server 2017 | 19 THE QUARKXPRESS SERVER USER INTERFACE • Windows: [drive]:\Program Files\Quark\QuarkXPress Server 2017\log To download all logs to a non-server computer, click Show Transaction Log in the QuarkXPress Server Web interface, then click Download Logs on the home page. General Preferences — Email QuarkXPress Server can automatically notify someone by e-mail when the checkedout QLA license is about to expire. The Email tab (Administration > Preferences > General > Email) lets you specify where such e-mail messages should be sent. Use the Server field to specify the domain name or IP address of the e-mail server that QuarkXPress Server should use to send messages (for example, mail.quark.com). Use the Port field to specify the port number of the e-mail server that QuarkXPress Server should use to send messages. Valid values are from 0 to 255. Use the From to specify the source e-mail address the QuarkXPress Server application should use to send messages (for example, QXPSserver1@quark.com). Use the To to specify the e-mail address to which the QuarkXPress Server application should send messages (for example, QXPServerAdmin@quark.com). General Preferences — Authentication The Authentication tab (Administration > Preferences > General > Authentication) includes the following controls. Check Authenticate For Admin Requests to enable the Username and Password fields. These fields let you control access to administrative parameters and features. You can enter up to 32 characters. Renderer Preferences dialog box Use the renderer Preferences dialog box (Administration > Preferences > Renderer) to set up default preferences for use when projects are created in QuarkXPress Server. It includes the tabs described in the following topics. Many of these preferences come into play only when you create a project in QuarkXPress Server, either using a construct request or through a request handled by a custom QuarkXPress Server XTensions module. You can also set renderer preferences using the setrendererprefs request handler. For more information, see”setrendererprefs.” Preferences — Display The Display pane (Administration > Preferences > Renderer > Display) includes the following controls. Use the Color TIFFs drop-down list to specify the color depth of screen previews created for color TIFFs when they are imported. 20 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE Use the Gray TIFFs drop-down list to specify the resolution of screen previews created for grayscale TIFFs when they are imported. Choose a profile that corresponds to your monitor from the Monitor Profile dropdown menu, or choose Automatic. Profiles can be placed in the “Profiles” folder in the QuarkXPress Server application folder. Preferences — Input Settings The Input Settings tab (Administration > Preferences > Renderer > Input Settings) includes the following controls. Check Smart Quotes to force QuarkXPress to replace feet (‘)and inches (“) marks automatically with the specified quotation marks. Use the Format drop-down menu to specify the default characters to be used with the Smart Quotes feature and Convert Quotes option in the Get Text dialog box (File > Get Text). To change the separators used for indicating sequential ranges for output, enter a value in the Sequential Page Range Separator. This value override the preferences set for a project. To change the separators used for indicating nonsequential ranges for output, enter a value in the Non Sequential Page Range Separator. This value override the preferences set for a project. Preferences — Font Fallback The Font Fallback pane (Administration > Preferences > Renderer > Font Fallback) includes the following controls. Check Font Fallback to activate the Font Fallback feature. When this feature is active, if the application encounters a character it cannot display in the current font, it attempts to find a font that can display the character. If the application encounters a missing font when opening a project, it uses the preferences in this pane to determine which substitute fonts to use. If you add characters to an exising project and the font cannot support those characters, the application will search the system for a font that can display the characters. Check Search to have the application search for a suitable font that is used in the active project. To restrict the search to a particular range, choose an option from the Search Type drop-down menu. To search the entire story where a missing font occurs, choose Active Story. To search a particular number of paragraphs in both directions, choose Paragraph and enter a number in the Search Limit field. To indicate which fallback fonts should be used when no other font can be found (taking the Search settings into account), choose options from each of the dropdown menus in the Font List area. To indicate which font should be used for the slug line when a layout is printed with registration marks turned on, choose an option from the Slug Line Font dropdown menu. A Guide to QuarkXPress Server 2017 | 21 THE QUARKXPRESS SERVER USER INTERFACE Preferences — Open and Save The Open and Save pane (Administration > Preferences > Renderer > Open and Save) includes the following controls. Choose an option from the Encoding drop-down menu to indicate how the applications should display characters in non-Unicode text. Preferences — Fonts The Fonts pane (Administration > Preferences > Renderer > Fonts) includes the following controls. To specify default replacement fonts, check Specify Default Replacement Font and choose options from the Roman and East Asian drop-down menu. To highlight characters that are in a Traditional Chinese encoding’s UDA/VDA (User Defined Area/Vendor Defined Area) range so that these characters can be visually verified, check Highlight character ranges defined by Traditional Chinese font vendors. Preferences — EPS The EPS pane (Administration > Preferences > Renderer > EPS) includes the following controls. To control whether the application should generate a preview of an EPS file or use the preview (if any) embedded in the file, choose an option from the Preview dropdown list. The option specified in this pane is used only when the EPS preview is being created. If you change the preference, you need to reimport the EPS file. Preferences — PDF Use the PDF pane of the Preferences dialog box (Administration > Preferences > Renderer > PDF) to set preferences for rendering in PDF format. The PDF pane displays only if PDF Filter XTensions software is loaded. For more information, see “PDF Filter XTensions software.“ Use this pane to specify a PDF workflow: • Click DirectPDF to generate PDF output in the browser. This is the default option. • Click PDFtoFolder to generate and save PDF files to a folder. Click Select/Browse to specify a location for the folder in the Watched Folder field. • Click PS4D (PostScript File for Later Distilling) to generate a PostScript file. Click Select/Browse to specify a location for the folder in the Watched Folder field. Use this pane to set the desired PDF output style. Choose from the following output styles: • Default PDF Output Style • Print - Medium Quality/Medium Resolution • PDF/X-1a:2001 22 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE • PDF/X-3:2002 • Press - High Quality/High Resolution • Print - Medium Quality/Medium Resolution • Screen - Low Quality/Low Resolution • Screen - Medium Quality/Low Resolution Use this pane to specify the folder path for the distiller error log file. The path is used by the PDFFilter XTension software to create the log file to log the errors that occur during the distillation process. The default path to the log file is /Documents. If you choose to change the default, the log folder specified must be a pre-existing folder on the system. Preferences — Project General Settings The Project General Settings pane (Administration > Preferences > Renderer > Project General Settings) includes the following controls. Check Use OpenType Kerning to activate the default kerning values for OpenType fonts. When OpenType kerning is active, it overrides any kerning specified through Kerning Table Edit (Utilities menu) for OpenType fonts. To disable OpenType kerning for full-width characters, check Do Not Kern Full Width Characters. Preferences — Print Layout Settings The Print Layout Settings pane (Administration > Preferences > Renderer > Print Layout Settings) includes the following controls. Use the Master Page Items drop-down menu to control what happens to master items when master pages are applied. • Click Keep Changes if you intend modified master items on your layout pages to remain when a new master page is applied. The items that are kept are no longer master items. • Click Delete Changes if you want modified master items on your layout pages to be deleted when a new master page is applied. Use the Framing drop-down menu to specify whether frames are placed inside or outside text and picture boxes. • When you click Inside, the distance between the text and the frame is determined by the box’s Text Inset values (Item > Modify). When you place a frame inside a picture box, the frame overlaps the picture. • When you click Outside, the frame is placed outside the box, increasing the box’s width and height. The frame cannot extend beyond a constraining box or the pasteboard. Use the Auto Page Insertion drop-down menu (Print layouts only) to determine whether pages are inserted automatically to contain text overflow from an automatic text box or a chain of text boxes (on a page associated with a master page A Guide to QuarkXPress Server 2017 | 23 THE QUARKXPRESS SERVER USER INTERFACE that contains an automatic text box). The drop-down menu also enables you to determine where any pages will be inserted. Preferences — Print Layout Measurements The Print Layout Measurements pane (Administration > Preferences > Renderer > Default Print Layout Measurements) includes the following controls. Use the Horizontal and Vertical drop-down menus to specify the measurement system for the rulers displayed along the top and left of the layout window. Horizontal corresponds to the top ruler; Vertical corresponds to the left ruler. Use the Points/Inch field to override the default value of 72 points per inch. The application uses the value here as the basis for all point and pica measurements, as well as for all point- and pica-to-inch conversions. The desktop publishing standard for points per inch is 72. However, the traditional typographic standard used on most metal typographic rulers is usually approximately 72.27 or 72.307 points per inch (range = 60 to 80 pt, measurement system = points, smallest increment = .001). Use the Ciceros/cm field to specify a ciceros-to-centimeter conversion value different from the standard 2.1967 (range = 2 to 3 c, measurement system = ciceros, smallest increment = .001). Preferences — Paragraph The Paragraph pane (Administration > Preferences > Renderer > Paragraph) includes the following controls. Use the Auto Leading feature to automatically set line spacing. Unlike paragraphs with absolute leading (identical line spacing above every line), paragraphs with auto leading may include lines with different leading when fonts and font sizes are mixed in the same paragraph. Auto leading starts with a base amount of leading, which the application calculates by examining the ascent and descent values built into the fonts used in an autoleaded line and the line above it; however, the user-specified text size plays the largest part in determining this base amount. Finally, a value specified by the user in the Auto Leading field is added to the base amount to arrive at the total amount of leading. To specify percentage-based auto leading, enter a value from 0% to 100% in 1% increments. This value determines the amount of leading between two lines of text as follows: The largest font size in the line above is multiplied by the percentage value. This outcome is added to the base amount of auto leading between the two lines. Although the design of certain fonts complicates the process, here is a simplified example: 10-point text styled consistently in a “standard” font with Auto Leading set to 20% has 12 points of leading (10 pts + [20% of 10] = 12 pts). Use the Maintain Leading check box to control the placement of a line of text that falls immediately below an obstruction in a column or box. If Maintain Leading is checked, the line’s baseline is placed according to its applied leading value. If Maintain Leading is unchecked, the ascent of the line will abut the bottom of the obstruction or any applied runaround value. In the Lock to Grid Based On area: 24 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE • Click Ascent and Descent to lock text to grid based on the ascenders and descenders of characters. • Click Font Size (Em Box) to lock text to grid based on the size of the em boxes of the characters. Preferences — Character The Character pane (Administration > Preferences > Renderer > Character) includes the following controls. Use the Superscript fields to control the placement and scale (size) of superscript characters. The Superscript Offset value determines how far below the baseline the application places a superscript character. The Superscript Offset value is measured as a percentage of font size. The default value is 33%. The Superscript VScale value determines the vertical size of the character and is a percentage of font size. The Superscript HScale value determines width and is a percentage of the normal character width (as specified by the font designer). The default value for both scales is 60% (range = 0 to 100%, measurement system = percentage, smallest increment = .1). Use the Subscript fields to control the placement and scale (size) of subscript characters. The Subscript Offset value determines how far above the baseline the application places a subscript character. The Subscript Offset value is measured as a percentage of font size. The default value is 33%. The Subscript VScale value determines the vertical size of the character and is a percentage of font size. The Subscript HScale value determines width and is a percentage of the normal character width (as specified by the font designer). The default value for both scales is 100% (range = 0 to 100%, measurement system = percentage, smallest increment = .1). Use the Small Caps fields to control the scale of characters with the Small Caps type style applied to them. The Small Caps VScale value determines the vertical size of the character and is measured as a percentage of font size. The Small Caps HScale value determines width and is measured as a percentage of the normal character width (as specified by the font designer). The default value for both scales is 75% (range = 0 to 100%, measurement system = percentage, smallest increment = .1). Use the Superior fields to control the scale of superior characters. The Superior VScale value determines the vertical size of the character and is measured as a percentage of font size. The Superior HScale value determines width and is measured as a percentage of the normal character width (as specified by the font designer). The default value for both scales is 60% (range = 0 to 100%, measurement system = percentage, smallest increment = .1). Use the Ligatures Break Above field to use ligatures built into a font. A ligature is a typographic convention in which certain characters are combined into a single glyph. Most fonts contain ligatures for the characters “f” followed by “i” and “f” followed by “l”. The Ligatures Break Above field enables you to specify the kerning or tracking value (measured in 1/200 em space increments) above which characters will not be combined into ligatures. For example, a headline with a large tracking value would probably not contain ligatures. The default value is 1 (range = 0 to 10, measurement system = .005 [1/200] em space, smallest increment = .001). To A Guide to QuarkXPress Server 2017 | 25 THE QUARKXPRESS SERVER USER INTERFACE prevent the second two letters in “ffi” and “ffl” (as in office and waffle) from being combined into ligatures, check Not “ffi” or “ffl”. Three-character ligatures for these combinations, common in traditional typesetting systems, are not standardized in fonts designed for Mac OS, so some typographers prefer to keep all three letters separate rather than combine only two of them. Note that many PostScript fonts do not have “ffi” and “ffl” ligatures, but most OpenType fonts do. This option is unchecked by default. Check Auto Kern to specify that the application should use kerning tables, which are built into most fonts, to control intercharacter spacing. The Auto Kern Above field enables you to specify the point size above which automatic kerning must be used. The Auto Kern Above feature also implements custom tracking information specified in the Tracking Values dialog box for a selected font (Utilities > Edit Tracking) in QuarkXPress. This option is checked by default, with a 4-point threshold (range = 0 to 72 pt, measurement system = various [“, pt, cm, etc.], smallest increment = .001). Check Standard Em Space to specify an em-space equivalent to the point size of the text (for example, 24pt text has a 24pt em space). If Standard Em Space is unchecked, the application uses the width of the two zeros in the current font as the em-space width. This option is checked by default. You can insert an em space in text by pressing Option+space/Ctrl+Shift+6. Use the Flex Space Width field to change the 50% default width of a flexible space. To create a breaking flexible space, press Option+Shift+space/Ctrl+Shift+5; to create a nonbreaking flexible space, press Command+Option+Shift+space/Ctrl+Alt+Shift+5. The Flex Space Width value is expressed as a percentage of the normal en space for a given font and font size (range = 0 to 400%, measurement system = percentage, smallest increment = .1). Use the Accents for All Caps check box to specify whether to include accent marks on accented characters with the All Caps type style applied. This option is checked by default. Use the Space between CJK & R field to indicate how much space should be included by default between a Chinese, Japanese, or Korean character and an adjacent Roman character. Preferences — Trapping The Trapping pane (Administration > Preferences > Renderer > Trapping) includes the following controls. Select a Trapping Method: • Click Absolute to trap using the values in the Auto Amount and Indeterminate fields according to the object and background colors involved. If the object color is darker, the object is choked by the background using the Auto Amount value. If the object color is lighter, the object is spread into the background using the Auto Amount value. • Click Proportional to trap using the value in the Auto Amount field multiplied by the difference between the luminance (lightness or brightness) of the object color and the background color. 26 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE • Click Knockout All to turn off trapping and print objects with a zero trap amount. Check Process Trapping to trap each process separation plate individually when a page contains overlapping process colors. Check Ignore White to specify that an object color in front of multiple background colors (including white) does not take white into account when trapping. Enter a trapping value in the Auto Amount field or choose Overprint: • Enter a value in the Auto Amount field to control the amount of trapping that QuarkXPress applies to object and background colors that have an Auto Amount specified in the Trap Specifications dialog box (Edit > Colors > Edit Trap), and to control the amount of trapping applied to items with an Auto Amount (+) Trap Information or (–) specified in the Trap Information palette (Window > Trap Information). • Choose Overprint to cause overprinting for object and background colors with an Auto Amount specified in the Trap Specifications dialog box (Edit > Colors > Edit Trap), as well as for items with an Auto Amount (+) or (–) specified in the Trap Information palette (Window > Trap Information). Enter a trapping value in the Indeterminate field or choose Overprint: • Enter a value in the Indeterminate field to control the amount of trapping that QuarkXPress applies to object colors that are in front of indeterminate backgrounds (multiple colors with conflicting trapping relationships). • Choose Overprint to cause an object color to overprint an indeterminate background. Enter a Knockout Limit value. The knockout limit is the value (expressed as a percentage of darkness of the object color) that enables you to control the point at which an object color knocks out a background color. Enter an Overprint Limit value. Overprint limit is a trapping setting that allows an object set to overprint to trap according to the Auto Amount value if the object’s shade is less than a particular percentage. Preferences — Color Manager The Color Manager pane (Administration > Preferences > Renderer > Color Manager) includes the following controls. To specify an engine for color transformation, choose an option from the Color Engine drop-down menu. To achieve the darkest possible blacks in all output methods, check Black Point Compensation. Use the Source Setup drop-down menu to specify the source color space of pictures and colors used in the application. To enable the Profile Information command in the Window menu and the Color Management tab in the Import Picture dialog box, check Enable Access to Picture Profiles. This option allows you to view information about profiles. A Guide to QuarkXPress Server 2017 | 27 THE QUARKXPRESS SERVER USER INTERFACE To specify a default proof output setup, choose an option from the Proof Output drop-down menu. To specify a rendering intent for soft proofing, choose an option from the Rendering Intent drop-down list. Perceptual scales all the colors in the source gamut so that they all fit within the destination gamut. Relative Colorimetric retains colors that are in both the source gamut and the destination gamut. The only source colors that are changed are those that are not within the destination gamut. Saturation considers the saturation of source colors and changes them to colors with the same relative saturation in the destination gamut. Absolute Colorimetric retains colors that are in both the source gamut and the destination gamut. Colors that are outside the destination gamut are adjusted in relation to how they would look when printed on white paper. Defined by Sources uses the rendering intents defined in source setup for all colors and images. To color manage vector content in imported EPS and PDF files, check Color Manage Vector EPS/PDF. Note that this preference applies only to EPS and PDF files imported after this box is checked. To color manage vector content in EPS and PDF files that have already been imported in the active project, check Include Existing Vector EPS/PDF in Layout. Preferences — Layers The Layers pane (Administration > Preferences > Renderer > Layers) has the following controls. To make new layers visible by default, check Visible. To suppress the printout of new layers by default, check Suppress Output. To make new layers locked by default, check Locked. To maintain runaround on new layers so that text on visible layers flows around items on hidden layers, click Keep Runaround. Preferences — Kindle Use the Kindle pane (Administration > Preferences > Renderer > Kindle) to specify the location of the KindleGen tool, which is required for Kindle output. To get a free copy of KindleGen, visit https://kdp.amazon.com/selfpublishing/help?topicId=A3IWA2TQYMZ5J6. Preferences — Modifier Use the Modifier pane (Administration > Preferences > Renderer > Modifier) to control whether and where errors are displayed in rendered layouts. To include descriptions of rendering errors in the layout itselt, check Annotate errors in the Output Document. (For more information, see “annotateerrors.”) In rendered QuarkXPress files, errors are displayed as notes. In rendered PDFs, errors are displayed as comments. In XML output, errors are displayed as notes XML markup. 28 | A Guide to QuarkXPress Server 2017 THE QUARKXPRESS SERVER USER INTERFACE To append descriptions of rendering errors after the last page, check Append errors into the Output Document. (For more information, see “appenderrors.”) Descriptions of rendering errors are formatted in 10-point magenta Arial. Job Jackets dialog box The Job Jackets dialog box lets you edit the Job Jackets file used by QuarkXPress Server. To edit the QuarkXPress Server Job Jackets file: 1. In the QuarkXPress Server Web interface, choose Administration > Job Jackets. The Manage Job Jacket dialog box displays. 2. Click the Get Job Jacket for editing button and save the Job Jackets file to the desktop. 3. Open the downloaded Job Jackets file in QuarkXPress and make any necessary changes to the QXPSJobTicket Job Ticket. 4. In the Job Jacket dialog box, click Choose File and select the modified Job Jackets file. 5. Click Submit. The QuarkXPress Server Job Jackets file is replaced with the modified version. App Studio preferences The AppStudio dialog box lets you specify credentials and proxy settings so that QuarkXPress Server can upload HTML5 App Studio articles to the App Studio Publishing Portal. Enter your App Studio Publishing Portal user name and password, then enter the proxy settings for your proxy server (if any). Check Out License dialog box To check the QuarkXPress Server license out of Quark License Administrator, choose Administration > Check Out License. To specify the number of days for checkout, enter a value in days in the Check out for field. To be warned in advance of license expiration, check Warn me and use the corresponding fields. A Guide to QuarkXPress Server 2017 | 29 USING QUARKXPRESS SERVER Using QuarkXPress Server The xml namespace deconstructs a project according to the Modifier DTD. The construct namespace lets the server turn an XML representation of a QuarkXPress project back into an actual project. With these namespaces, you can deconstruct a project into an XML representation, change the XML in accordance with the Modifier DTD, and then have the server generate an updated version of the QuarkXPress project. You can even create new QuarkXPress projects from scratch using XML. In addition, you can use the construct namespace to: • Create a page based on master page • Create a project from XML, using a Job Jackets™ file as the basis for the project • Modify text font and style, including OpenType® styles • Apply style sheets and local formatting to text • Create and populate tables • Import pictures into picture boxes and specify picture attributes The DTD used for XML construction and deconstruction is completely Unicode®compliant, making it ideal for use in international publishing. Furthermore, the use of this DTD ensures that the schema of XML output created by Constructor does not change when server preferences change. This DTD is provided in the QuarkXPress Server application folder and fully documented in “Modifier DTD (annotated).” Deconstructor XTensions software and the deconstruct namespace are no longer supported. Creating URL requests You can use URL requests to make QuarkXPress Server render projects in a variety of formats, to use the features of server XTensions modules, and to control the server. The topics below provide an overview of how to construct server requests and use URL parameters. This chapter also lists functions that let you control the server. For detailed information about constructing other types of URL requests, see “Web integration.” Understanding URL requests QuarkXPress Server URL requests should use the following format: 30 | A GUIDE TO QUARKXPRESS SERVER 2017 USING QUARKXPRESS SERVER http://server:port/namespace/path/projectname?parameter=value • server: Indicates the name or IP address of the QuarkXPress Server computer. • port: Indicates the QuarkXPress Server application’s port number. The default • namespace: Sets the render type (or indicates another server functionality to • port number is 8080. access). For more information, see “Understanding QuarkXPress Server namespaces.“ path: Indicates the path to the directory where the target project file is stored. The project to be rendered can either be located in the document pool (in which case paths are evaluated relative to the document pool directory), or can be streamed as part of a multipart HTTP Post request. When the project is streamed as part of the request, the project name will correspond to the name given to the • • HTTP request part which contains the project data. projectname: Identifies the project to be rendered. parameter=value: Optional parameters that provide more detailed control over how the target project should be rendered. Multiple parameter/value pairs, separated by the “&” character, can be included. For example, the following URL asks the QuarkXPress Server application named “QXPServer” to return the file “MyProject.qxp” as a PDF file with hyperlinks and all fonts embedded: http://QXPServer:8080/pdf/MyProject.qxp?includehyperlinks=1&embed allfonts=1 Some URL parameters require Boolean arguments. For such parameters, valid values include 1 or 0, true or false, y or n, and yes or no. You can also send requests to QuarkXPress Server using the HTTP GET and POST protocols and using XML with XSLT. For more information about these approaches, see “Web integration.” Understanding QuarkXPress Server namespaces QuarkXPress Server namespaces differentiate among types of requests that are otherwise identical. For example, consider the following three URLs: http://QXPServer:8080/project1.qxp http://QXPServer:8080/pdf/project1.qxp http://QXPServer:8080/postscript/project1.qxp These requests are identical, except each uses a different namespace (in italic). (The first request does not specify a namespace, but this simply means the project is to be rendered using the server’s default render type.) Namespaces can be used to determine the format in which a rendered project is returned, as indicated above, but they can also be used to direct a request to XTensions software that performs other functions. For example, if you use Modifier XTensions software’s xml namespace, Modifier XTensions software can return an XML representation of the project. A Guide to QuarkXPress Server 2017 | 31 USING QUARKXPRESS SERVER Looking up a namespace This guide lists the namespaces for every QuarkXPress Server function. There is no single list of namespaces because some functions do not require a particular namespace or are available in multiple namespaces. To determine which namespace you want to use: 1. In this Guide, go to the page that documents the render type you want to use. (For more information, see “Understanding render types.”) 2. Locate the Namespace row. If the render type or function has an associated namespace, that namespace is listed here. Third-party XTensions can add their own namespaces. For information about a third-party namespace, see the documentation for the XTensions module that adds that namespace. Understanding QuarkXPress Server parameters Parameters let you control the details of how a request is executed. For example, you can use the page parameter to create a request that returns only the third page of a project: http://QXPServer:8080/jpeg/project1.qxp?page=3 You can include multiple parameters in the same request; simply separate them with an ampersand (&). For example, here’s a new version of the above URL that returns page three at a scale of 50%: http://QXPServer:8080/jpeg/project1.qxp?page=3&scale=.5 Looking up a parameter This Guide lists the parameters that are available for every QuarkXPress Server function. To determine which parameters you can use with a request: 1. In this Guide, go to the page that documents the the render type you want or the function you want to use. (For more information, see “Understanding render types“ and “Understanding render modifiers.”) 2. Locate the Parameters row. This row lists all available parameters, and includes a description and a list of valid values for each parameter. Supported interfaces The following interfaces are available in QuarkXPress Server: • HTTP: Lets you interact with the server using URLs that contain calls or point to XML files that contain calls. You can write client applications in any language that supports HTTP requests. For more information, see “Getting started: HTTP“. • HTTPS: Provides secure HTTP access. • Web services: Lets you interact with the server via Web services using the QuarkXPress Server Manager object model. You can write client applications in 32 | A Guide to QuarkXPress Server 2017 USING QUARKXPRESS SERVER Java, .NET, or any other programming language that can consume SOAP-based Web services. For more information, see “Getting started: Web services“. To develop a custom load balancer or a custom application in Java, you must have version 1.5 or 1.6 of the JDK. The Dynamic Publishing Process (DPP) The Dynamic Publishing Process (DPP) has several stages. You may not need to use all of these stages every time, but this the order in which they occur: • Pre-Processing Stage: During this stage, QuarkXPress Server performs any necessary initial steps, such as creating style sheets, colors, and H&J rules for a new QuarkXPress project. • Content Loading Stage: During this stage, QuarkXPress Server loads dynamic content into boxes in the project. • Layout Modification Stage: During this stage, QuarkXPress Server modifies the layout of the project. • Post-Processing Stage: During this stage, QuarkXPress Server examines the project and performs maintenance tasks. Getting started The topics below describe how to create requests for the QuarkXPress Server Web interface. For information about the options available in such requests, see “Using the Web interface.” Getting started: HTTP and HTTPS You can submit HTTP and HTTPS requests to QuarkXPress Server as URLs, either manually from a browser or automatically from an HTTP client application. QuarkXPress Server processes such requests and returns rendered content in the HTTP or HTTP responses. Depending on the type of request, the QuarkXPress Server preferences, and the type of content returned, the rendered content may be downloaded by the end user, displayed in the end-user’s browser, or saved to a file system location accessible to QuarkXPress Server. You can write a QuarkXPress Server client application in almost any language that can generate HTTP GET/POST requests. A QuarkXPress Server HTTP-based solution typically consists of QuarkXPress Server (running on a server computer connected to a network) plus a front-end application (usually Web-based) that provides a graphical user interface (GUI) for end users. The front-end application translates end users’ input into HTTP or HTTPS requests and sends the requests to QuarkXPress Server or QuarkXPress Server Manager, which processes the requests and returns rendered content. A Guide to QuarkXPress Server 2017 | 33 USING QUARKXPRESS SERVER Dissecting a QXP Server URL To interact with QuarkXPress Server from a Web browser, use a URL like the following: http://[server]:[port]/[namespace]/[directory]/[DocumentName]?[pa rameter]=Value • • [server]: The name or IP address of the computer for QuarkXPress Server or QuarkXPress Server Manager. [port]: The port number on which to contact QuarkXPress Server or QuarkXPress Server Manager. The default port is 8080 for QuarkXPress Server and 8090 for QuarkXPress Server Manager. • [namespace]: Defines what the URL action will be and any parameters and • [directory]: The path in the document pool where the project is stored, conditions available to that namespace. relative to the QuarkXPress Server document pool. To access the root level, no directory path is necessary. (Note that you can also supply assets as part of a multipart HTTP request. For more information, see “Using HTTP POST with QXP • • Server.”) [DocumentName]: The name of the QuarkXPress project to be processed. [parameter]: Further defines the URL action with attributes and values allowed for the namespace or general call. Pass parameters in the form attribute=value, with parameters separated by the “&” character. For QuarkXPress Server Manager, use a URL like the following: http://[server]:[port]/qxpsm/request/[namespace]/[directory]/ [DocumentName]?[parameter]=Value Prior to QuarkXPress Server 9.0, you had to use different URL constructions when sending requests to an instance of QuarkXPress Server Manager in a QPS installation than you did when sending requests to a free-standing instance of QuarkXPress Server Manager. In versions 9.0 and later, both can use /qxpsm/request/ after [port]/ . You can now use both absolute and relative paths when you modify a project with SDK objects or classes. Relative paths are almost always relative to the document pool. If you use multiple QuarkXPress Server instances, you should use a common document pool. Interpreting the QXP Server Manager response When QuarkXPress Server Manager successfully processes a request through the HTTP interface, the response is the same as QuarkXPress Server’s response unless the user has supplied additional parameters to QuarkXPress Manager. For more information, see “Working with QuarkXPress Server Manager” in A Guide to QuarkXPress Server. If an error occurs, QuarkXPress Server Manager retries the request, either on the same QuarkXPress server instance or a different one (depending on the error and global settings established in the QuarkXPress Server Manager client). If QuarkXPress Server Manager cannot process the request, it returns an XML response 34 | A Guide to QuarkXPress Server 2017 USING QUARKXPRESS SERVER describing the error, plus any header error codes returned by QuarkXPress Server. For example: HTTP GET and POST Requests The topics below describe how you can use HTML to interact with QuarkXPress Server. QuarkXPress Server supports both the GET and POST HTML methods. When you use the GET method, the browser encodes form data into a URL. When you use the POST method, form data is passed within the message body. Use the GET method only when the form processing is idempotent. In short: GET is for retrieving data, whereas POST can involve storing or updating data, ordering a product, or sending an e-mail. Using HTTP GET with QXP Server Use HTML like the following to specify a server and port where you want to send a request. You can specify the name of the target project, the output type, and a scaling value. You can specify the name of a box and the path of a text or picture files to import into that box, as long as the file’s path is on the server’s file system. You can also use HTML like the following to specify the page number and layout number of the project. The form section of the HTML should begin with the following line of code: 500 -43 File not found. M8000001 The server could not locate the specified file.