RFC - Proposed updated Table of Contents

[dmitrizagidulin]

Since the intention is to port the book from its original format to Pillar (which doesn't, as far as I know, support the notion of Parts or Book Sections (a way to group Chapters)), some thought should be put into a slight re-formatting of the table of contents to make it a slightly flatter hierarchy.

I propose the following chapters:

1. Foreword
2. Introduction
3. Getting started
   • with sections by smalltalk distribution, like in original Part I
4. Component Basics
   • with sections for:
   • Rendering Components
   • CSS
   • Anchors and Callbacks
   • Forms
5. Using Components
   • calling components
   • embedding components
   • tasks
6. Seaside In Action
   • A Simple ToDo Application
   • A Web Sudoku Player
7. Serving Files
8. Managing Sessions
9. Ajax and Comet
   • jQuery
   • Dynamic Content with Scriptaculous (somewhat obsolete now)
   • Comet
10. RSS
    • the Really Simple Syndication chapter from the Web 2.0 part
11. Deploying Seaside
12. REST Services
13. Persistence
14. Magritte: Meta-data at Work
15. Writing good Seaside Code
    • (extracted from the Seaside in Action part, since this is standalone topic)

[DamienCassou]

@dmitrizagidulin Pillar handles LaTeX book parts the same way it handles all other section types. You just have to use !:

! Part A
!! Chapter A.1
!! Chapter A.2
! Part B
...

then, you have to map the number of ! and the LaTeX section type using headingLevelOffset. In HTML, you use the same trick to convert the number of ! to either <h1> or <h2> or ...

[dmitrizagidulin]

@DamienCassou I made a stab at a parts + chapter structure here: 9940083 (if you scroll down to the bottom, there's an image of the rendered ToC).

I wasn't able to nest the chapters within the parts directory, since that seemed to break the relative ../support links somewhere, during compile. But, a flat directory structure's fine.

[dmitrizagidulin]

@DamienCassou one more question, related.
How do you put in a Foreword, for example, that won't be numbered in the table of contents?

[DamienCassou]

I wasn't able to nest the chapters within the parts directory, since that seemed to break the relative ../support links somewhere, during compile. But, a flat directory structure's fine.

Pillar now supports this. Instead of referencing relative links like ../support you add a root prefix to all your paths root/support. root will be created automatically and will contain everything in the support pillar.conf parameter. In LaTeX, you have to use subimport so that imported file can import other files using paths relative to their directory. E.g., add \subimport{root/support/latex/}{common.tex} to your LaTeX chapter template. You can get inspired from https://github.com/SquareBracketAssociates/EnterprisePharo/

[DamienCassou]

How do you put in a Foreword, for example, that won't be numbered in the table of contents?

I've never tried that from Pillar. For EnterprisePharo we put the foreword in a LaTeX master file directly. You may try changing the LaTeX Mustache template for this particular file and making sure the pillar file itself does not have any chapter definition (i.e., no line starting with !)

[Ducasse]

I do not understand because I cannot add a comment to the license file.
Pay attention the seaside book license is not the same as the other book. So far the PDF is sold.
I will see if I want to give it to the community.

[dmitrizagidulin]

@Ducasse - what do you mean, you can't add comment to the license file?

And, tell me more, about the book license? I was just going by what it said on the bottom of the book web site, "This book is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 license." Is that not the actual license?

[dmitrizagidulin]

@DamienCassou - I'll see if I can figure it out (the nested support links, and the Foreword). Thanks!

[dmitrizagidulin]

E.g., add \subimport{root/support/latex/}{common.tex} to your LaTeX chapter template.

@DamienCassou - I can't seem to get this to work. Here's the start of my chapter latex template:

\ifx\wholebook\relax\else
    % Lulu:
    \documentclass[a4paper,10pt,twoside]{book}
    \usepackage[
        papersize={6.13in,9.21in},
        hmargin={.75in,.75in},
        vmargin={.75in,1in},
        ignoreheadfoot
    ]{geometry}
    \usepackage{import}
    \subimport{root/support/latex/}{common.tex}
    \input{../support/latex/common.tex}
    \setboolean{lulu}{true}

And it gives me something like:

! LaTeX Error: File `common.tex' not found.
Enter file name: ./Introduction.tex:13: Emergency stop. 
<read *>
l.13    \subimport{root/support/latex/}{common.tex}

Do I need the line \usepackage{import}? (The Enterprise Pharo template has it)

[dmitrizagidulin]

Trying out @DamienCassou's suggestion of using ! for Parts, and !! for chapters. (Still can't get chapters in nested directories working).

Pillar handles LaTeX book parts the same way it handles all other section types. You just have to use !:

! Part A
!! Chapter A.1
!! Chapter A.2
! Part B
...

Here's what the ToC looks like now:

This looks OK (although it doesn't quite capture the same chapter numbering as the online book's ToC, that's not a required goal).

What I don't like is how it renders Part I as Chapter 2:

I suspect this is what Damien meant by "you have to map the number of ! and the LaTeX section type using headingLevelOffset", but I can't figure out how to do that.

I'm going to go with the "flat" chapter structure proposed at the start of this discussion, for the moment.

[DamienCassou]

@cdlm with sbabook, how can we have a paragraph introducing a part? As you can see above, Getting Started is a part containing several chapters (e.g., Pharo Smalltalk). With sbabook,

\part{Getting Started}

This part will show you how to get a simple Seaside application up and running in your favourite Smalltalk dialect in less than 15 minutes.

will put the paragraph 2 pages after the page with the "Getting Started" title

[DamienCassou]

I've created a book with the structure I think you want: https://github.com/DamienCassou/pillar-seaside-book. The result is in the book-result/ directory of this repository. If you need more information, please ask. The only problem I see with the result is the blank pages between the part's title and the part's introduction. I hope @cdlm has a solution.

[cdlm]

Hard to say. If I understood correctly, the default behavior is that part,
introductory paragraph, and chapter opening are on three successive
right-hand pages. Setting the intro paragraph just below the part title
could make sense, but on the verso, facing the chapter opening, not so much.

Of course, the implementation can be hacked, but that is highly dependent
on how \part and \chapter are defined in the document class.

On 8 December 2015 at 11:37, Damien Cassou notifications@github.com wrote:

I've created a book with the structure I think you want:
https://github.com/DamienCassou/pillar-seaside-book. The result is in the
book-result/ directory of this repository. If you need more information,
please ask. The only problem I see with the result is the blank pages
between the part's title and the part's introduction. I hope @cdlm
https://github.com/cdlm has a solution.

—
Reply to this email directly or view it on GitHub
#2 (comment)
.

Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet