Skip to content

Latest commit

 

History

History
240 lines (219 loc) · 13 KB

WORKLOG.adoc

File metadata and controls

240 lines (219 loc) · 13 KB

WORKLOG

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

    • perhaps progit2 as well; others?

TODO

  • upgrade Treetop

  • rename example to basic-example and chronicles to chronicles-example

  • recognize inline image syntax in page_background_image key

  • allow front cover and back cover image to be defined in theme; document in theming-guide

  • keep caption with table (check for sufficient space)

  • allow caption placement for table to be configurable (top vs bottom)

  • allow valign to be set on image block (vertical center in page for things like slides)

  • separate theme control for listing vs literal block (and maybe source too)

  • allow title page image "bottom" to be set instead of "top" (mutually exclusive)

  • scale block images like inline images

  • rewrite optimize-pdf using rghost

    • add Optimizer class; wire to cli

  • pass macro doesn’t work in source block when macro subs and highlighting are both enabled

  • bind image_registry between scratch and main document so we don’t process the same image more than once

    • need to do some testing

  • title is being rendered 3 times (maybe one for scratch?); explain why in comments if normal

  • finish docs/theming-guide.adoc

    • continue working on json schema for theme; try to generate keys section from it

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

    • look closer at line_height and line_height_length and see if we need to document other details

  • 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?

  • add index support

  • add entry to TOC for preamble/preface

  • can we create fragments in converter instead of using the formatted text parser?

  • allow text alignment of prose to be set in document

  • don’t issue warnings on scratch document

  • rake release seems messed up (tagging the wrong commit)

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

  • 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)

  • should we rename base_ to body_ to make it more familiar to CSS developers?

  • support !include in theme file (file issue)

  • margin per heading level (see asciidoctor#176)

  • add cover page example to chronicles so people see how to use it

  • images

    • multiple image width by 0.75 to get point value (including in running header and footer)

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

  • don’t orphan a single line of paragraph (send it with a buddy line)

  • implement stem support

  • fail gracefully if theme file cannot be found

  • dedicated style for top/bottom margin of outline list

    • 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

  • need dedicated theme styles for paragraph spacings, etc

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

  • recto/verso indentation (on body?)

  • 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)

  • 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

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

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

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

  • should 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)

  • document what each keep_together is doing / expects

    • keep_together really needs to pick up the inherited horizontal bounds or else measurement is inaccurate

  • 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

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

    • split prawn_ext/extensions into individual files based on function

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

  • enable text_transform for table foot row

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

  • 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)

  • 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)

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

  • remove pdfmarks file after optimizing

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

  • 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

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

  • document how the treetop parser is rebuilt

  • 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

  • stop using fallback fonts in default theme (instead, bundle a fuller font)

  • 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

  • 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 (only applies to embedded images)

  • honor font defs in SVG (to get M+ 1p); prawn-svg supports loading fonts; need to pass fonts to prawn-svg

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

  • disable monospace color in headings

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

  • 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

  • reorganize 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

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

  • introduce method for start_initial_page?

  • 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)

  • ttfunk does not support ligatures (e.g., fi → fi); we could do this manually in post_replacements

Potential Optimizations

  • if autofit is set on a listing/literal block that has conums, we are splitting fragments by line twice

Usage Optimizations

  • uncompress PNG files

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

  • font families used in SVGs must match keys in the font catalog

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? I think we should keep it because it provides context elsewhere in the document (e.g. $base_font_size vs $font_size)