Added chapter 25

[lehonma]

TODOs:

• ~Add high-res imgs~ (jonas says: they are generally ok for now)
• [x] Review

[aszasz]

@jonas: I am not sure I should open an issue for the bellow, which I think is an unexpected behavior \include{10-station-amenities.manu} halts during html generation if the file starts with \subsection{Station Amenities} No problem occurs if the content of the file is moved to 09-station-architecture as it is on the pr.

I let comments on files (including the error with DEBUG =1)... the behavior is unexpected right

do you want me to submit the one that fails on another pr or maybe in my fork? or do you want me to try to fix it (I would look for something related with the position recording)

[jonasmalacofilho]

I'm going to take a look at this right now!

Btw: you just mentioned a complete stranger : )

[jonasmalacofilho]

I'm debugging the issue...

So far I have been able to confirm that the generated transform.Document is invalid, and that this issue is correlated to the \include.

DChapter: brt-stations
├ DSection: principles-of-station-design
├ DSection: basic-concepts
├ DSection: station-capacity
│ ├ DSubSection: station-sub-stops
│ ├ DSubSection: high-capacity-system-stations
│ ├ DSubSection: medium-capacity-system-stations
│ ├ DSubSection: low-capacity-system-stations
│ ├ DSubSection: modularity-and-scalability
├ DSection: types-of-stations
│ ├ DSubSection: island-stations
│ ├ DSubSection: split-stations
│ ├ DSubSection: offset-stations
│ ├ DSubSection: directional-stations
├ DSection: station-location
├ DSection: station-dimensions
│ ├ DSubSection: station-length
│ ├ DSubSection: station-width
│ ├ DSubSection: station-height
│ ├ DSubSection: station-and-road-cross-sections
├ DSection: station-components
│ ├ DSubSection: access--arrival-area
│ ├ DSubSection: entrance-area-and-fare-collection
│ ├ DSubSection: number-of-gates-ticket-machines-or-boots
│ ├ DSubSection: layout-and-placement-of-turnstiles
│ ├ DSubSection: platform-waiting-and-circulation-areas
│ ├ DSubSection: wayfinding
│ ├ DSubSection: its-components
│ ├ DSubSection: seating
├ DSection: vehicle-interface
│ ├ DSubSection: doors-and-boarding-area
│ ├ DSubSection: platform-vehicle-alignment
├ DSection: station-architecture
│ ├ DSubSection: architectural-style
│ ├ DSubSection: weather-and-enclosure
│ ├ DSubSection: lighting-and-power-supply
│ ├ DSubSection: signature-and-iconic-stations
│ ├ DSubSection: supervision-during-construction
│ ├ DSubSection: ensuring-high-quality-construction
│ ├ DSubSection: demonstration-stations
│ ├ DSubSection: materials
│ │ ├ DSubSubSection: passive-heating-and-cooling
│ │ ├ DSubSubSection: mechanical-heating-and-cooling
│ │ ├ DSubSubSection: electricity
│ ├ DSubSection: greenery
├ DSubSection: station-amenities
├ DSection: station-operation
│ ├ DSubSection: brt-station-staffing
│ ├ DSubSection: maintenance-of-brt-stations
│ ├ DSubSection: cleaning-of-brt-stations
│ ├ DSubSection: security-and-vandalism
│ ├ DSubSection: emergencies-and-evacuation
│ ├ DSubSection: special-events

Code

```haxe /* Generate a hierarchy tree of the current DElem */ public static function hiercharchyTree(v:DElem, lowLevel=false) { var buf = new StringBuf(); function f(offset:Int, v:DElem) { var hi = v.def.match(DVolume(_)|DChapter(_)|DSection(_)|DSubSection(_)|DSubSubSection(_)); var lo = v.def.match(DBox(_)|DTable(_)|DList(_)|DElemList(_)); if (hi || (lowLevel && lo)) { if (offset > 0) { for (i in 1...offset) buf.add("│ "); buf.add("├ "); } if (lo) buf.add("*"); buf.add(Type.enumConstructor(v.def)); if (v.id != null) { buf.add(": "); buf.add(v.id); } buf.add("\n"); iter(v, f.bind(offset+1)); } else { iter(v, f.bind(offset)); } } f(0, v); return buf.toString(); } ```

---

This might have something to do with the non-flattened structure of immediately nested transform.Document.DElemList we noticed earlier (from the stack trace).

[jonasmalacofilho]

The complete vertical structure hierarchy is (including non sectioning elements with vertical children):

Long output ... click to expand

``` DChapter: brt-stations ├ *DElemList │ ├ *DList │ ├ *DList │ ├ *DElemList │ │ ├ DSection: principles-of-station-design │ │ │ ├ *DElemList │ │ │ │ ├ *DList │ │ │ │ ├ *DList │ ├ *DElemList │ │ ├ DSection: basic-concepts │ │ │ ├ *DElemList │ │ │ │ ├ *DList │ │ │ │ ├ *DList │ │ │ │ ├ *DList │ │ │ │ ├ *DList │ ├ *DElemList │ │ ├ DSection: station-capacity │ │ │ ├ *DElemList │ │ │ │ ├ *DList │ │ │ │ ├ *DTable: classification-of-selected-brt-systems-into-high--medium--and-low--capacity-stations │ │ │ │ ├ DSubSection: station-sub-stops │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: high-capacity-system-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: medium-capacity-system-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: low-capacity-system-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: modularity-and-scalability │ │ │ │ │ ├ *DElemList │ ├ *DElemList │ │ ├ DSection: types-of-stations │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: island-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: split-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: offset-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: directional-stations │ │ │ │ │ ├ *DElemList │ ├ *DElemList │ │ ├ DSection: station-location │ │ │ ├ *DElemList │ │ │ │ ├ *DList │ ├ *DElemList │ │ ├ DSection: station-dimensions │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: station-length │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DTable: sub-stops-and-queuing-spaces-required │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DBox: transmilenio-stations │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: station-width │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DBox: example-of-station-width-requirement-calculation │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: station-height │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: station-and-road-cross-sections │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DTable: typical-elements-in-a-cross-section-at-a-brt-station │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DList │ ├ *DElemList │ │ ├ DSection: station-components │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: access--arrival-area │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DTable: summary-of-problems-and-consequences-identified-in-the-transjakarta-busway-from-december-2008 │ │ │ │ ├ DSubSection: entrance-area-and-fare-collection │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: number-of-gates-ticket-machines-or-boots │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DBox: finding-out-how-many-gates-are-required │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DTable: example-of-number-of-required-gates-computation │ │ │ │ ├ DSubSection: layout-and-placement-of-turnstiles │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: platform-waiting-and-circulation-areas │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: wayfinding │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: its-components │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: seating │ │ │ │ │ ├ *DElemList │ ├ *DElemList │ │ ├ DSection: vehicle-interface │ │ │ ├ *DElemList │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: doors-and-boarding-area │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: platform-vehicle-alignment │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ *DBox: solutions-to-minimizing-the-gap-a-case-study │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ ├ *DElemList │ │ ├ DSection: station-architecture │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: architectural-style │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: weather-and-enclosure │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: lighting-and-power-supply │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: signature-and-iconic-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: supervision-during-construction │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: ensuring-high-quality-construction │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: demonstration-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: materials │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ DSubSubSection: passive-heating-and-cooling │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ DSubSubSection: mechanical-heating-and-cooling │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ │ │ ├ *DList │ │ │ │ │ │ ├ DSubSubSection: electricity │ │ │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: greenery │ │ │ │ │ ├ *DElemList │ ├ *DElemList │ │ ├ DSubSection: station-amenities │ │ │ ├ *DElemList │ ├ *DElemList │ │ ├ DSection: station-operation │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: brt-station-staffing │ │ │ │ ├ DSubSection: maintenance-of-brt-stations │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: cleaning-of-brt-stations │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: security-and-vandalism │ │ │ │ │ ├ *DElemList │ │ │ │ ├ DSubSection: emergencies-and-evacuation │ │ │ │ │ ├ *DElemList │ │ │ │ │ │ ├ *DList │ │ │ │ ├ DSubSection: special-events │ │ │ │ │ ├ *DElemList ```

---

I see two problems with this:

• unnecessary nesting (there's actually a reason for that amount of nesting: keeping accurate position information)
• the incorrect placement of DSubSection: station-amenities must come from a bug in transform.Transform.consume : \

[jonasmalacofilho]

Ok, I now know what causes the issue.

Basically, transform.Transform follows the parser.AST (keyword: tree) and can't handle subsections that aren't decedents of sections. And that particular file organization causes the AST to look something like this:

VElemList for file: 00-index.manu
├ VElemList for file: 01-principles-of-station-design.manu
├ [...]
├ VElemList for file: 09-station-architecture.manu
│ ├ Section: station-architecture
│ │ ├ DSubSection: architectural-style
│ │ ├ [...]
│ │ ├ DSubSection: greenery
├ VElemList for file: 10-station-amenities.manu
│ ├ SubSection: station-amenities

EDIT: the above structure is a hypothesis, not a real world dump! And #186 suggests that the problem is a bit more complex than that.

[jonasmalacofilho]

@aszasz : because of the file structure we adopted, I'm comfortable with 09-station-architecture.manu being a good (if not the best) place for that subsection.

I opened a separate issue for the problem we identified and I'll try to tackle soon(ish).