WORKLOG.adoc

WORKLOG

• use Groovy language specification as case study to find corner cases

  • perhaps progit2 as well; others?

TODO

• source highlighting (with Pygments) not working inside an admonition block (see chronicles.adoc)

  • don’t need to run source highlighter in dry run

• getting a line wrap break before comma if preceding word is emphasized (problem in Prawn wrapping)

• don’t create blank page first page if content overflows and we’re on the first page (already fixed?)

• toc

  • make dot leader style separate from title / number

• running content

  • side margins (allow override, default to content margins)

  • numbered and unnumbered chapter and section titles (file issue)

  • chapter and section number (easily solved by previous)

  • separate running content for chapter page (by default uses normal content)

• support !include in theme file

• theming guide

  • document arbitrary keys (such as brand colors)

  • document transparent color

  • document unicode values

  • document how to load theme (with special attention to fonts & images)

  • positional meanings of array items

• images

  • multiple image width by 0.75 to get point value

  • should we use native size of image by default? (after multiplying by 0.75)

• implement stem support

• rethink how we are handling line heights for fonts, then document carefully

• dedicated style for top/bottom margin of outline list

• need dedicated theme styles for paragraph spacings, etc

• can’t put margin top on chapter (chapter_top?)

• allow margin top and bottom to be set for lists (applies to outer-most list)

• allow spacing between nested lists levels be configured in theme

• recto/verso indentation (on body?)

• implement first-line indent for paragraphs (seems like conflict w/ our text formatter)

  • option to not indent first paragraph in section

  • if you indent, perhaps drop the margin between paragraphs?

• don’t indent and draw line next to quote block unless width > 0 or color != transparent

• subtitles for chapters

• part titles need their own page and styling

• add color calculation functions in theme file (like in SASS)

• remove asciidoctor-theme.yml until we’re ready to recreate it

• create utility method to get % offset of page as y value (option to constrain to bounds)

• document converter assignment in convert_content_for_block method

• support transparency for colors

• support generic color (or value) attribute in formatted text parser instead of specific color systems (rgb, cmyk)

• file issue to import PDF page using block image macro

• allow theme_font to set line_height (honor this setting from document)

  • theme setting for code line height (currently using base_line_height)

• show we put an entry for doctitle in the outline if notitle is set? (need to test these edge cases)

• use docdate attribute to set modification date on document (file issue)

• more theme control over toc (font size, style, color per level)

• don’t allow formatted text (e.g., monospace) in toc entries

• prevent title-logo-image from spilling to next page (same with title content)

• support font family and style for heading level

• document what each keep_together is doing / expects

• split prawn_ext/extensions.rb into individual modules and include them

• code cleanups (regexps to constants, nil? checks and such)

  • fix the background color mess in convert_table

  • extract regex in ThemeLoader into constant

  • remove dead code dealing with margins

  • remove unused theme / font files

  • decide how we want to format theme_loader.rb (should be consistent)

• enable line above (or below?) title on title page (file issue)

• text_transform for table foot row

• file upstream issue for Prawn to warn if it can’t resolve a glpyh (or monkeypatch it)

• make use of shrink_to_fit where appropriate

• support web fonts; use uri-cache to avoid redundant fetching

• allow pdf-page-layout (portrait || landscape) to be set in document

• attribute or role to control table shading (all, even, odd) (or call it striped like bootstrap?)

• make conum glyphs configurable in theme (use reference table to resolve)

• add pdf page import support to the image block macro (file issue)

• do we still need the converter hack in convert_content_for_block? (seems to be needed for admonitions)

• avoid getting an empty last page (example: colist at bottom of page can cause this)

• utility to coerce the color value transparent to nil (better handling in general)

• CJK and/or multilingual support

• description list term should keep together with content (file issue)

• GhostScript Tiger SVG is reporting incorrect height when embedded (too much spacing below); bug in prawn-svg?

• hardbreak in table cell results in extra endline (likely not normalizing cell content)

• don’t create new page if content overflows and we’re on the first page

• parse pdf-page-size syntax 8.5in x 11in (or optional square brackets)

• remove pdfmarks file after optimizing

• add note to README that Prawn will subset any fonts provided

• nested keep_together logic is broken (e.g., example inside example, listing inside sidebar, etc)

• look into single_line + shrink_to_fit in listings, perhaps other places

• refactor as Prawn view to avoid method name conflicts (also see prawnpdf/prawn#802)

• make CodeRay theme colors configurable (in theme?)

• create proper default (Asciidoctor) theme

• implement compat lists (like in Asciidoctor EPUB3)

• list bullet in ordered list needs to grow with length of number

• document how the treetop parser is rebuilt

• rewrite optimize-pdf using rghost

  • add Optimizer class; wire to cli

• use ImageMagick to uncompress PNG images before reading them (could also just document this)

• rework font so we can set actual height, calculate x_height internally (use 1em for spacings)

• padding top and bottom on content affects height_of calculations (need to review)

• code font needs to support more than just ascii (Golo license block is an example)

• don’t cutoff content in partintro

• use padding from theme around admonition block content

• use padding from theme around block quote content

• add admonition_label_font_color to theme

• remove remaining uses of vertical_rhythm and horizontal_rhythm

• honor safe mode rules

• allow cover images to be specified by theme as a fallback

• verify cover image exists; fail gracefully with warning

• using fallback fonts significantly slows down Prawn because it checks every letter every time (see https://github.com/prawnpdf/prawn/blob/master/lib/prawn/text/formatted/box.rb#L427-L434)

• print scratch.pdf file if verbose / trace mode is on in Asciidoctor

• introduce setting to indent section content

• design merge margin logic (like for admonition block)

• rename default theme to docbook theme, make default the Asciidoctor theme (should we have a base theme?)

• allow relative font size for inline code to be set (perhaps a percentage or em value? there are problems with this in arranger)

• set defaults in ThemeLoader for required theme settings like prose_margin_top/bottom so we don’t need fallbacks in code

• implement orphan sentences for paragraph

• apply line height metrics for table content

  • figure out how to adjust line height for monospaced cell content

  • figure out how to layout regular cell content to adjust for line height

• document the typeset_text methods very clearly

• fix shading on listing that spans more than one page

  • in general, need to deal w/ situation if content in dry run is large than one page

  • need to deal w/ situation if content in dry run is large than one page

• move check for node.title? inside layout_caption

• theme idea / tester: see sandbox/ebook-learn_version_control_with_git-SAMPLE.pdf

• make alternating page title position optional (via theme?)

• BUG: page numbers are off in Clojure Cookbook

• fix passthrough placeholders that get caught up in syntax highlighting (see https://github.com/asciidoctor/asciidoctor/blob/master/test/blocks_test.rb#L2258-L2277)

• we could eliminate some of the tags we’re currently matching in the formatted text parser (e.g., link)

• add Preamble to TOC

• NOTE prawn-svg supports loading from a URI

• should we support % as a unit in theme (divides by 100 and sets float value)?

• enable pagenums attribute by default (may require changes to how we handle attributes)

• start page numbering on first page if no title page

• implement quote style from default Asciidoctor stylesheet

• reorg Prawn extensions (see prawn-table for example)

• rename "theme" to "style"?

• restrict custom theme path to jail (or load from load_path)

• implement convert_toc

• can get orphan conum if starts on last line of page (fixed already?)

• only create title page if doctype=book

• disable monospace color in headings

• add source language to upper-left corner of listing block

• italic text in a line of text styled as bold in the theme loses its bold style

• introduce method for start_initial_page?

• honor font defs in SVG (to get M+ 1p)

• callout matching in listing blocks is extremely fragile and doesn’t handle two in one line

• make outline a document option (perhaps "outline" like "toc")

• shrink / squeeze source code to avoid wrapping (see original impl in nfjsmag, also shrink_to_fit)

• add bench/ directory for the script to test the speed of the formatted text parser

• start page numbering on page 1 (use /PageLabels reference to make i the title page number)

  • add this feature upstream to Prawn

• report image only page w/ stamps corruption issue to Prawn

• add /PageMode /UseOutlines

• what does fopub do to calculate scaling images? reduces width more?

• replace tabs with spaces in source code (Asciidoctor core change?)

• preamble on separate page?

• part on separate page for book doctype? (which other sections?)

• make default image scale width a theme setting

• cli arguments

  • theme (pdf-style, pdf-stylesdir)

  • enable/disable writing pdfmarks file

  • optimize-pdf

• section numbering

• implement footnotes correctly

• image border

• table footer

• flesh out outline more

• flesh out title page more

  • document subtitle (partially solved)

• don’t create title page for article doctype

• implement toc and activate if toc is set on document (need to reorder pages)

• inline image

• callbacks for title page, new part, new chapter, etc

• split out render methods for chapter, part, section, etc

• custom subs in verbatim blocks

• captions/titles on all blocks that support them

• make font size and character spacing scaling of inline code part of theme

• customizable character spacing

• might be able to avoid dry run for listing/literal in obvious cases

• implement index of index terms

• bw theme for CodeRay to match output of Pygments bw

• inline tabs should be replaced in layout_prose (etc) when normalize is enabled

• use treetop to parse and evaluate theme file

• make source code highlighting theme configurable (should be now, but has problems with conums)

• use or don’t use pad method? check performance

Documentation

• control page numbering using pagenums attribute

• "Incorrect number of arguments in 'SCN' command" happens when you add a stamp to an imported page

• be mindful that layout_prose adds margin to bottom of content by default (important when working in a bounding box)

Usage Optimizations

• uncompress PNG files

• avoid the fallback font if possible (use full fonts in your theme)

Open Questions

Design

• remove/reduce padding above heading when it appears at the start of a page?

• Default line height?

• Should the heading sizes be calculated according to the default font size?

• Page margins

• Body indentation?

  • recto / verso indentation?

• Size of masthead / footer

• Line separating masthead / footer?

• Separate title page

• Start chapter on new page?

• Special layout for chapter page?

Theme

• keep or drop base_ prefix in theme?

Resources

• Origami PDF: A PDF inspection library

• A theme for PDF designed for printing