asciidoctor-lists-extended 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 763b4829cf12a23c7ae9c993f9f10fc394919af9adb8c4e5eaf34f82a017ce76
-  data.tar.gz: 1a22a3265585f57715f25d0f14f8d3c44889eb9efd9976698dd7aa42b760dc46
+  metadata.gz: c1f0396e93370444193a1258530dd32f81db35dddaedc4c911a31655d94d5e2c
+  data.tar.gz: bbd4f0412e6b11fcfc1bb39b38a2cd9932c8738a740d8c6b693f4185c03c0566
 SHA512:
-  metadata.gz: 3260b2cbe8a43684258c6a2a9e33f0e236b01453e99dc4cec4dcf967f15011c1f8f96daf833160d7e24d18593838d6752271050b22fc53a6f8edfcd58ccc77bd
-  data.tar.gz: f42056096abc9bd690b97abbffcc40ee61ad3dc8f64b4f041eec42ec5fbdf87de9c61e5605cdf608eb4e73b5e0105ec0ce04c74ff79e99e70ffe290035f4c3cf
+  metadata.gz: 9970ef9f04375ee8e446abb219171880806ac09bdc09f1909f0830eda569e37191188cd195813185339e56b31ccaaf6446f835415f77d5adaf912b6bf032aee3
+  data.tar.gz: fe43e888bba80b85b9212f24df7bed543224e510f22e4b40aefd754eeacf27b0e5e22220d2bc9a3d70e684dacab1e00d49ab120547b74382b6ad9bdc86bda824

data/README.adoc

@@ -1,13 +1,30 @@
 = asciidoctor-lists-extended
 :toc: left
 :toclevels: 2
-:source-highlighter: rouge
+:source-highlighter: highlight.js
 
 A converter-aware asciidoctor extension that generates a *List of Figures*, *List of Tables*, *List of Listings*, and *List of Examples* — or any custom captioned block type.
 
 Replaces and supersedes `asciidoctor-pdf-lofte`.
 Compatible with the `asciidoctor-lists` macro syntax.
 
+== Preview
+
+.Table of Contents with List of Figures, List of Tables, and List of Examples entries
+image::test/images/toc.png[PDF Table of Contents showing list entries,pdfwidth=100%]
+
+.List of Figures — dot-leader style matching the ToC
+image::test/images/lof.png[List of Figures rendered in PDF front matter,pdfwidth=100%]
+
+.List of Listings
+image::test/images/lol.png[List of Listings rendered in PDF front matter,pdfwidth=100%]
+
+.List of Examples
+image::test/images/loe.png[List of Examples rendered in PDF front matter,pdfwidth=100%]
+
+.PDF bookmark outline showing list entries
+image::test/images/pdf-outline.png[PDF bookmark outline panel,pdfwidth=100%]
+
 == Features
 
 * Works with *HTML5* (xref links) and *asciidoctor-pdf* (dot-leader style matching the ToC)
@@ -47,13 +64,13 @@ asciidoctor -r /path/to/lib/asciidoctor-lists-extended.rb document.adoc
 :toc:
 :doctype: book
 
-\== List of Figures          <1>
+== List of Figures          <1>
 list-of::image[]             <2>
 
-\== List of Tables
+== List of Tables
 list-of::table[]
 
-\== Chapter 1
+== Chapter 1
 
 .My Architecture Diagram     <3>
 image::arch.png[]
@@ -165,7 +182,7 @@ In PDF mode the extension hooks into `asciidoctor-pdf`'s ToC allocation/renderin
 All lists are placed in the *front matter* (directly after the ToC) regardless of where the `list-of::` macros appear in the source.
 The macro order in the source determines the order of the lists in the front matter.
 
-You can place additional `list-of::` macros inside chapter subsections to generate *chapter-scoped* lists.
+You can place `list-of::` macros inside any subsection to generate *section-scoped* lists.
 The scope is determined automatically from where the macro appears in the document hierarchy:
 
 [cols="1,2"]
@@ -176,30 +193,41 @@ The scope is determined automatically from where the macro appears in the docume
 e.g. a front-matter `== List of Figures`
 |*Document-wide* — collects all matching elements in the entire document.
 
-|Inside a subsection (`=== …`) nested within a chapter +
+|Inside a subsection (`=== …`) +
 e.g. `=== Chapter 1 Figures` inside `== Chapter 1`
-|*Chapter-scoped* — collects only elements from that chapter and its child sections.
+|*Section-scoped* — collects only elements placed inside that same subsection.
 |===
 
-.Example: global list plus a per-chapter list
+[IMPORTANT]
+====
+For section-scoped lists, place the captioned content *before* the `list-of::` macros
+within the subsection.
+This ensures all entries have already been rendered when the list runs, so page numbers
+show correctly (no `?`).
+====
+
+.Example: global list plus a per-section list
 [source,asciidoc]
 ----
-\== List of Figures        <1>
+== List of Figures        <1>
 list-of::image[]
 
-\== Chapter 1
+== Chapter 1
 
-.Overview Diagram
-image::arch.png[]
+=== Chapter 1 Figures    <2>
 
-\=== Chapter 1 Figures    <2>
-list-of::image[]
+.Overview Diagram         <3>
+image::arch.png[]
 
 .Detailed Flow
 image::flow.png[]
+
+list-of::image[]          <4>
 ----
-<1> Document-wide: collects all images.
-<2> Chapter-scoped: collects only Chapter 1's images.
+<1> Document-wide: collects all images across the entire document.
+<2> Subsection that owns both the content and the scoped list.
+<3> Captioned images placed *before* the macro so page numbers are resolved.
+<4> Section-scoped: collects only images placed inside `=== Chapter 1 Figures`.
 
 === Styling
 
@@ -250,19 +278,19 @@ The containing section and heading are rendered normally.
 :table-caption: Table
 :listing-caption: Listing
 
-\== List of Figures
+== List of Figures
 list-of::image[]                                        <1>
 
-\== List of Tables
+== List of Tables
 list-of::table[hide_empty_section]                      <2>
 
-\== List of Code Examples
+== List of Code Examples
 list-of::listing[title="Code Examples"]                 <3>
 
-\== List of Appendix Examples
+== List of Appendix Examples
 list-of::example[exclude_from_outline]                  <4>
 
-\== Chapter 1: Architecture
+== Chapter 1: Architecture
 
 .System Overview
 image::arch.png[]
@@ -332,10 +360,10 @@ The `list-of::` macros render as `<ul>` lists with `<a href="#…">` links.
 
 |`:lof-title: List of Figures` +
 `:lot-title: List of Tables`
-|`\== List of Figures` +
+|`== List of Figures` +
 `list-of::image[]` +
  +
-`\== List of Tables` +
+`== List of Tables` +
 `list-of::table[]`
 
 |`:include-lists-in-toc:`

data/lib/asciidoctor-lists-extended/html_renderer.rb

@@ -64,13 +64,7 @@ module Asciidoctor
       def scope_node_for(block, document)
         node = block.parent
         return document unless node.respond_to?(:context) && node.context == :section
-        node.parent.context == :document ? document : chapter_ancestor(node)
-      end
-
-      def chapter_ancestor(section)
-        node = section
-        node = node.parent while node.parent&.context == :section
-        node
+        node.parent.context == :document ? document : node
       end
 
       # Parse AsciiDoc source lines in the context of +parent+, returning the

data/lib/asciidoctor-lists-extended/pdf_converter.rb

@@ -29,7 +29,8 @@ module Asciidoctor
         super
         @list_extents                  = {}   # UUID → Extent (front-matter lists only)
         @list_configs_ordered          = []   # front-matter list configs in document order
-        @inline_list_configs           = {}   # UUID → config for chapter-scoped inline lists
+        @inline_list_configs           = {}   # UUID → config for section-scoped inline lists
+        @inline_render_positions       = {}   # UUID → deferred render position (page + cursor)
         @inline_num_front_matter_pages = 0    # saved from ink_toc for inline page-number math
         @rendering_list                = false
         @list_toc_insert_idx           = 0
@@ -89,7 +90,29 @@ module Asciidoctor
           @list_toc_insert_idx += 1
         end
 
-        super
+        result = super
+
+        # Phase 2: render deferred inline section-scoped lists.
+        # traverse doc has completed before ink_toc is called, so all
+        # pdf-page-start attributes are now set and page numbers are real.
+        unless @inline_render_positions.empty?
+          @inline_render_positions.each_value do |pos|
+            go_to_page pos[:page]
+            move_cursor_to pos[:cursor]
+            entries = get_list_entries(pos[:config][:scope_node], pos[:config][:element])
+            next if entries.empty?
+            entries.each { |e| e.level = 2 if e.title }
+            begin
+              @rendering_list = true
+              ink_toc_level entries, pos[:num_levels], pos[:dot_leader], num_front_matter_pages
+            ensure
+              @rendering_list = false
+            end
+          end
+          go_to_page page_count
+        end
+
+        result
       end
 
       # -----------------------------------------------------------------------
@@ -122,19 +145,69 @@ module Asciidoctor
       # cursor position without a heading (the enclosing === section provides
       # the heading) and without any page break before or after.
       # All other paragraphs delegate to super unchanged.
+      # -----------------------------------------------------------------------
+      # convert_paragraph override
+      # -----------------------------------------------------------------------
+      # Intercepts UUID placeholder paragraphs for section-scoped inline lists.
+      #
+      # Rendering strategy (two-phase):
+      #   Phase 1 — body rendering (here, scratch? may be true or false):
+      #     • When scratch? is true: call ink_toc_level in scratch mode so Prawn
+      #       measures the correct space for page-break decisions.
+      #     • When scratch? is false: dry-run the list to measure its height,
+      #       reserve that space in the document by advancing the cursor, and
+      #       record the page + cursor position in @inline_render_positions.
+      #       No visible content is written yet.
+      #
+      #   Phase 2 — ink_toc (called by asciidoctor-pdf AFTER traverse doc):
+      #     By the time ink_toc runs all pdf-page-start attributes have been set.
+      #     For each saved position, navigate there and render with real dot leaders
+      #     and page numbers.  See ink_toc below.
       def convert_paragraph(node)
         if node.content_model == :simple && node.lines.size == 1 &&
            (config = @inline_list_configs[node.lines[0]])
+          uuid    = node.lines[0]
           entries = get_list_entries(config[:scope_node], config[:element])
+
           unless entries.empty?
             entries.each { |e| e.level = 2 if e.title }
-            num_levels = (node.document.attr 'toclevels', 2).to_i
+            num_levels = @theme.toc_levels || 2
             dot_leader = build_dot_leader_config(num_levels)
-            begin
-              @rendering_list = true
-              ink_toc_level entries, num_levels, dot_leader, @inline_num_front_matter_pages
-            ensure
-              @rendering_list = false
+
+            if scratch?
+              # Scratch pass (e.g. heading orphan detection): measure space only.
+              begin
+                @rendering_list = true
+                ink_toc_level entries, num_levels, dot_leader, 0
+              ensure
+                @rendering_list = false
+              end
+            else
+              # Real pass: measure via dry_run, reserve blank space, save position.
+              extent = dry_run(onto: self) do
+                begin
+                  @rendering_list = true
+                  ink_toc_level entries, num_levels, dot_leader, 0
+                ensure
+                  @rendering_list = false
+                end
+              end
+
+              save_page   = extent.from.page
+              save_cursor = extent.from.cursor
+
+              # Reserve the space without rendering any content.
+              extent.each_page { |first_page| start_new_page unless first_page }
+              move_cursor_to extent.to.cursor
+
+              @inline_render_positions[uuid] = {
+                config:     config,
+                entries:    entries,
+                num_levels: num_levels,
+                dot_leader: dot_leader,
+                page:       save_page,
+                cursor:     save_cursor,
+              }
             end
           end
           return

data/lib/asciidoctor-lists-extended/pdf_renderer.rb

@@ -134,24 +134,16 @@ module Asciidoctor
       # Determine the collection scope for a list-of:: UUID placeholder block.
       #
       # Rule: if the macro's parent section is a top-level section (its parent is
-      # the Document), scope is the whole document.  If the macro is nested inside
-      # a chapter (grandparent is another section), scope is the chapter ancestor —
-      # the first ancestor section whose parent is the Document.
+      # the Document), scope is the whole document.  Otherwise, scope is the direct
+      # parent section — the macro collects only elements within that subsection.
       #
       # This means front-matter lists (== List of Figures) collect everything, while
-      # per-chapter lists (=== Chapter Figures inside == Chapter 1) collect only
-      # their chapter's content automatically.
+      # per-section lists (=== Chapter Figures inside == Chapter 1) collect only
+      # elements placed inside that same subsection.
       def scope_node_for(block)
         node = block.parent
         return block.document unless node.respond_to?(:context) && node.context == :section
-        node.parent.context == :document ? block.document : chapter_ancestor(node)
-      end
-
-      # Walk up the parent chain to find the first section whose parent is the Document.
-      def chapter_ancestor(section)
-        node = section
-        node = node.parent while node.parent&.context == :section
-        node
+        node.parent.context == :document ? block.document : node
       end
 
       # Safe accessor: use the asciidoctor-pdf constant if available, else fall back.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-lists-extended
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - 白一百 baiyibai