Editor's Handbook: Using the Yucca engine

Yucca is the Web-based interface to Wikitravel Press' print conversion engine.

Login

You will be assigned a username and password for access to the system.

Select, Add, Delete

After logging in, all guidebooks you have access to will be listed.  To select or delete a project, choose its radio button and hit [Select] or [Delete].  To create a new project, choose [Add].

Adding a guidebook project

Enter the project name that will become the book title (eg. "Singapore" for Singapore) and a comma-separated list of usernames allowed access to the project.  If creation is successful, you will allowed to proceed to the chapter editor.

Deleting a guidebook project

You can delete guidebook projects from the selection menu.  This operation is permanent.

Note: At the moment, the guide is deleted from the database, but its files are kept on disk.  You can thus "restore" a project by recreating it with an identical name -- this will throw up a few warnings, but should work fine.

Navigation

Once you have logged in and selected a guide, a navigation bar will be displayed:



Select [change] to return to the guide selection menu, where you can also add or delete guides.

Select [logout] to log out of Yucca.

The other four links represent the four stages of the publishing process as explained below.

Edit

"Edit" allows you to define the contents of the guidebook.  This is done by specifying the Wikitravel articles to be imported in a text area.  Each article name must be on its own line, and special characters can be entered as is:

Singapore
Singapore/Little India
O'Hare International Airport

The articles will be assembled into the book the order they are listed here, with the titles listed here.  If you want to use a different title, you can enter it after a semicolon (";"):
Keep titles short.  Two noteworthy special cases:

1. The chapter whose name matches the book title (eg. "Singapore") is automatically renamed "Overview".
2. If you want to import a country article for a city, give it the name "Reference", and Yucca will automatically select only the relevant chapters.

In the Edit page, you can also give additional credits, acknowledgements and shouts out to your mom.  Special characters are generally OK and standard Wiki markup can be used.

Note: Please contact Jani if you need to adjust user permissions for an existing project.

Fetch

"Fetch" is used to download or update the contents of the guidebook.  The display shows all chapters currently included in the guidebook.   To download the content of a chapter (or all chapters), select its radio button and hit [Fetch].  Note the three checkboxes:

• Download guide: Fetch the text of the chapter, including attributions.
• Download images: Fetch all images referenced in the chapter, printable or otherwise.  Images will be compared to those already downloaded (if any) and any duplicates of identical size skipped.  Note: Image downloading is slow and error-prone, the size will be validated after completion and redownloaded if necessary.
• Overwrite: Download images even if they already exist and are the correct size. You're unlikely to ever need this.
  

Once the content has been fetched, you will be shown any differences to the previous edition.

To edit the list of chapters (see Edit), select [Edit chapters].  To proceed, select [Compile].

Note: Every guidebook project is considered a fully independent entity.  Thus, if even if you have many projects that reference the same articles or images, you have to fetch them separately in each project.

Compile

"Compile" is used to compile your wiki pages into a PDF file.  This is the core of the Yucca engine, and once kicked off you can't actually influence the process, but here's a guide to the steps of what's happening.

1. The chapters of the book are assembled together into a master wikitext (Singapore.wiki).
2. The master wikitext is preprocessed to eg. strip out comments and unnecessary blocks, alter some content positions and transform images into macros.
3. The master wikitext is converted into a LaTeX document (Singapore.tex).
4. The LaTeX document is compiled into the final PDF document (Singapore.pdf).  The exact cycle is compile, index, recompile, which allows page references etc to be defined accurately.
   

This generates huge amounts of log, which are largely meaningless most of the time, but useful for tracking down any bugs in the system.  Most "warnings" can be safely ignored, and only "fatal errors" will actually abort book production.  The end result is a PDF document, which you can and should download for verification.

Common errors: CONVERT phase

WARNING Listing has no name

Common errors: COMPILE phase

! Missing $ inserted.
<inserted text> 
                $
l.6094 St, _
            1 773 429-0666, Tu-Sa 11AM-7PM. You can buy just about anything

Curly brace should be preceded by a backslash: >>{<<{infobox

Publish

The final step is to publish the guidebook. For time being, though, the actual uploading of the file to Amazon still has to be done manually, and the "Publish" step only adds the WT/WTP ads to the end and moves the PDF to the final directory. Please notify Jani when you feel that you're ready for a test printing -- and note that it's best to do this sooner rather than later!

Miscellaneous

Fetching (esp. images) and compiling can take a while, so be patient.

In the not-too-unlikely event of getting completely stuck, Yucca does not always react kindly to being stopped, so it's best to wait for a TCP timeout.  If the system becomes completely unresponsive, try again in 15 minutes, and if it still doesn't work, please tell Jani.

Please notify Jani if you find any bugs in the GUI or engine, or have usability suggestions.

• For errors in the GUI, please include a screenshot.
• For errors during compilation, please cut and paste the log.  (If the problem occurred in the Convert phase, rerunning compilation with "debug" enabled may be helpful.)
  
• For errors in the PDF output, you do not need to attach the file as it's already on the server, just describe the problem and give me the name.

See also the Yucca master bug list.

Back to the Handbook