P1 = build it first
P2 = almost certainly build in next few days
P3 = say 'coming soon' in docs, wait until someone needs it or we have time.

GET  /brochure/MYDOC/   - renders our search page
    #options to expand sections (P1), pre-check sections (P1); and (maybe) 
    #control options on subsequent download page (P3)

    sections - Parameters as shown below in API section. Will have the effect of 
        checking the relevant tick boxes by default. For abstract sections, all
        sub-sections will be selected.

    sections-expanded - list of abstract sections that should be expanded by
        default on page load

    download-selection=(pdf|flipbook|email) - Which out of these three download
        options are selected by default (P3)

    download-display=(pdf,flipbook,email|all) - List of download options that
        are made available to user (comma separated list). not-set is same as 'all',
        otherwise list any combination of 'pdf,flipbook,email'. (P3)

    title,subtitle,blurb,header,footer,reference - Same as API below


POST /brochure/MYDOC/   - our page submitted, CSRF protected, leads to download page.
                          nobody but us should call this.

  /brochure/MYDOC/download - only used from our forms, do not call


GET/POST /brochure/mydoc/api  - for developers to call to make stuff.  
    Generally P2 but see below....
     
    disposition= 
        inline  - return PDF content, with 'Content-disposition: inline'
        attachment  - return PDF content, with 'Content-disposition: inline'
        html - return small, styled 'here is your link' page
        email (P2) - needs extra params (who to send to, auth..) but sends it.
                can be done later.  Returns 200 and short message, or some
                other code and meaningful error message?
        flip_book - check current code - is it a redirect?
                returns redirect to your personalised flipbook page
        url - makes on disk, returns text/plain with the URL where it can be found


    Section choice:  section params can be abstract or concrete.  Selecting
        an abstract section should select all its subsections. You do not need
        to list mandatory sections, as they will be included anyway.

    Style 1: P2
    sections=section1, section2, section3
        parse on commas.  Each one can be either an id or a slug.  Factor out
            the checking code.

    Style 2:  P3
    section_SLUGNAME=yes  will enable the section.
    section_SLUGID=yes  will enable the section.  (Include common HTML yes-values)


    Style 3:  P3
    subset=PREDEFINED_SUBSET_NAME - look in Subsets model to save looking up
        the sections in style 1 or 2.  This might need to take priority over
        the 'mandatory' stuff.   Low priority.

    #these things may be used for display.  Put them in an 'extra' dictionary
    #passed through to the generate_single_pdf_brochure function.  Ensure they default
    #to something ('' or sensible default, not None)


    P2  (display in generic binder table-of-contents for verification purposes;
        actual use will always be a change request or template related)
    title= large main title
    subtitle= smaller subtitle
    blurb=    a paragraph ("Here is your recommended holiday....")
    header=   used on inner page headers
    footer=   used on inner page footers
    reference=  a code you can pass through (e.g. deal ID, customer number)


GET /brochure/MYDOC/help (P1) a help page listing sections and explaining how to link
GET /brochure/MYDOC/sections (P2) - a JSON listing


#don't set this in stone yet...
GET /brochure/MYDOC/api/SUBSETNAME.pdf  (P3)

    Look for a model ('Subset' model and admin to be added) which defines
    a preset selection of sections.   Make that PDF.