diff options
34 files changed, 243 insertions, 236 deletions
diff --git a/.rubocop.yml b/.rubocop.yml index 5e6134b5..95822c3a 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -82,6 +82,13 @@ Style/CharacterLiteral: Enabled: false Style/ClassAndModuleChildren: Enabled: false +Style/CommentAnnotation: + Keywords: + - TODO + - FIXME + - HACK + - NOTE + - QUESTION Style/ConditionalAssignment: EnforcedStyle: assign_inside_condition IncludeTernaryExpressions: false @@ -8,7 +8,7 @@ gemspec gem 'asciidoctor', ENV['ASCIIDOCTOR_VERSION'], require: false if ENV.key? 'ASCIIDOCTOR_VERSION' gem 'open-uri-cached', require: false gem 'prawn-gmagick', ENV['PRAWN_GMAGICK_VERSION'], require: false if ENV.key? 'PRAWN_GMAGICK_VERSION' -# NOTE use prawn-table from upstream (pre-0.2.3) to verify fix for #599 +# NOTE: use prawn-table from upstream (pre-0.2.3) to verify fix for #599 gem 'prawn-table', git: 'https://github.com/prawnpdf/prawn-table', ref: '515f2db294866a343b05d15f94e5fb417a32f6ff', require: false gem 'pygments.rb', ENV['PYGMENTS_VERSION'], require: false if ENV.key? 'PYGMENTS_VERSION' gem 'rghost', ENV['RGHOST_VERSION'], require: false if ENV.key? 'RGHOST_VERSION' diff --git a/lib/asciidoctor/pdf/converter.rb b/lib/asciidoctor/pdf/converter.rb index 4c00c0c5..3a6419a7 100644 --- a/lib/asciidoctor/pdf/converter.rb +++ b/lib/asciidoctor/pdf/converter.rb @@ -35,7 +35,7 @@ module Asciidoctor attr_reader :text_decoration_width - # NOTE require_library doesn't support require_relative and we don't modify the load path for this gem + # NOTE: require_library doesn't support require_relative and we don't modify the load path for this gem CodeRayRequirePath = ::File.join __dir__, 'ext/prawn/coderay_encoder' RougeRequirePath = ::File.join __dir__, 'ext/rouge' PygmentsRequirePath = ::File.join __dir__, 'ext/pygments' @@ -91,7 +91,7 @@ module Asciidoctor square: ?\u25aa, none: '', } - # NOTE Default theme font uses ballot boxes from FontAwesome + # NOTE: default theme font uses ballot boxes from FontAwesome BallotBox = { checked: ?\u2611, unchecked: ?\u2610, @@ -131,7 +131,7 @@ module Asciidoctor htmlsyntax 'html' outfilesuffix '.pdf' if (doc = opts[:document]) - # NOTE enabling data-uri forces Asciidoctor Diagram to produce absolute image paths + # NOTE: enabling data-uri forces Asciidoctor Diagram to produce absolute image paths doc.attributes['data-uri'] = (doc.instance_variable_get :@attribute_overrides)['data-uri'] = '' end @initial_instance_variables = [:@initial_instance_variables] + instance_variables @@ -150,7 +150,7 @@ module Asciidoctor end def traverse node, opts = {} - # NOTE converter instance in scratch document gets duplicated; must be rewired to this one + # NOTE: converter instance in scratch document gets duplicated; must be rewired to this one if self == (prev_converter = node.document.converter) prev_converter = nil else @@ -185,7 +185,7 @@ module Asciidoctor preface.special = true preface.sectname = 'preface' preface.title = blk0.instance_variable_get :@title - # QUESTION should ID be generated from raw or converted title? core is not clear about this + # QUESTION: should ID be generated from raw or converted title? core is not clear about this preface.id = preface.generate_id preface.blocks.replace blk0.blocks.map {|b| b.parent = preface; b } # rubocop:disable Style/Semicolon doc.blocks[0] = preface @@ -292,7 +292,7 @@ module Asciidoctor toc_page_nums = @toc_extent ? (layout_toc doc, toc_num_levels, @toc_extent[:page_nums].first, @toc_extent[:start_y], num_front_matter_pages[1]) : [] # NOTE: delete orphaned page (a page was created but there was no additional content) - # QUESTION should we delete page if document is empty? (leaving no pages?) + # QUESTION: should we delete page if document is empty? (leaving no pages?) delete_page if page_count > 1 && page.empty? end @@ -327,7 +327,7 @@ module Asciidoctor def init_pdf doc (instance_variables - @initial_instance_variables).each {|ivar| remove_instance_variable ivar } if state pdf_opts = build_pdf_options doc, (theme = load_theme doc) - # QUESTION should page options be preserved? (otherwise, not readily available) + # QUESTION: should page options be preserved? (otherwise, not readily available) #@page_opts = { size: pdf_opts[:page_size], layout: pdf_opts[:page_layout] } ((::Prawn::Document.instance_method :initialize).bind self).call pdf_opts renderer.min_version (@pdf_version = PDFVersions[doc.attr 'pdf-version']) @@ -346,7 +346,7 @@ module Asciidoctor else @ppbook = nil end - # QUESTION should ThemeLoader handle registering fonts instead? + # QUESTION: should ThemeLoader handle registering fonts instead? register_fonts theme.font_catalog, (doc.attr 'pdf-fontsdir', 'GEM_FONTS_DIR') default_kerning theme.base_font_kerning != 'none' @fallback_fonts = [*theme.font_fallbacks] @@ -592,9 +592,9 @@ module Asciidoctor heading_height += (@theme.heading_min_height_after || 0) if sect.blocks? start_new_page unless cursor > heading_height end - # QUESTION should we store pdf-page-start, pdf-anchor & pdf-destination in internal map? + # QUESTION: should we store pdf-page-start, pdf-anchor & pdf-destination in internal map? sect.set_attr 'pdf-page-start', (start_pgnum = page_number) - # QUESTION should we just assign the section this generated id? + # QUESTION: should we just assign the section this generated id? # NOTE: section must have pdf-anchor in order to be listed in the TOC sect.set_attr 'pdf-anchor', (sect_anchor = derive_anchor_from_id sect.id, %(#{start_pgnum}-#{y.ceil})) add_dest_for_block sect, sect_anchor @@ -632,7 +632,7 @@ module Asciidoctor end end - # QUESTION if a footnote ref appears in a separate chapter, should the footnote def be duplicated? + # QUESTION: if a footnote ref appears in a separate chapter, should the footnote def be duplicated? def layout_footnotes node return if (fns = (doc = node.document).footnotes - @rendered_footnotes).empty? theme_margin :footnotes, :top @@ -660,7 +660,7 @@ module Asciidoctor unless (align = resolve_alignment_from_role node.roles) align = (@theme[%(heading_h#{hlevel}_align)] || @theme.heading_align || @base_align).to_sym end - # QUESTION should we decouple styles from section titles? + # QUESTION: should we decouple styles from section titles? theme_font :heading, level: hlevel do layout_heading node.title, align: align, level: hlevel, outdent: (node.parent.context == :section) end @@ -706,7 +706,7 @@ module Asciidoctor end end end - # QUESTION should we be adding margin below the abstract?? + # QUESTION: should we be adding margin below the abstract?? #theme_margin :block, :bottom end end @@ -774,7 +774,7 @@ module Asciidoctor icon_size = icon_data[:size] || 24 label_width = label_min_width || (icon_size * 1.5) # NOTE: icon_uri will consider icon attribute on node first, then type - # QUESTION should we use resolve_image_path here? + # QUESTION: should we use resolve_image_path here? elsif icons && (icon_path = node.icon_uri type) && (icon_path = node.normalize_system_path icon_path, nil, nil, target_name: 'admonition icon') && (::File.readable? icon_path) @@ -881,13 +881,13 @@ module Asciidoctor end embed_image image_obj, image_info, width: icon_width, position: label_align, vposition: label_valign rescue - # QUESTION should we show the label in this case? + # QUESTION: should we show the label in this case? log :warn, %(could not embed admonition icon: #{icon_path}; #{$!.message}) end end else - # IMPORTANT the label must fit in the alotted space or it shows up on another page! - # QUESTION anyway to prevent text overflow in the case it doesn't fit? + # NOTE: the label must fit in the alotted space or it shows up on another page! + # QUESTION: anyway to prevent text overflow in the case it doesn't fit? theme_font :admonition_label do theme_font %(admonition_label_#{type}) do # NOTE: Prawn's vertical center is not reliable, so calculate it manually @@ -987,7 +987,7 @@ module Asciidoctor end if node.attr? 'attribution' theme_font %(#{category}_cite) do - # NOTE temporary workaround to allow bare & to be used without having to wrap value in single quotes + # NOTE: temporary workaround to allow bare & to be used without having to wrap value in single quotes attribution = node.attr 'attribution' attribution = escape_amp attribution if attribution.include? '&' attribution_parts = [attribution] @@ -1049,7 +1049,7 @@ module Asciidoctor theme_fill_and_stroke_block :sidebar, box_height if box_height pad_box @theme.sidebar_padding do theme_font :sidebar_title do - # QUESTION should we allow margins of sidebar title to be customized? + # QUESTION: should we allow margins of sidebar title to be customized? layout_prose node.title, align: (@theme.sidebar_title_align || @base_align).to_sym, margin_top: 0, margin_bottom: (@theme.heading_margin_bottom || 0), line_height: @theme.heading_line_height end if node.title? theme_font :sidebar do @@ -1192,7 +1192,7 @@ module Asciidoctor term_font_styles = nil end terms.each do |term| - # QUESTION should we pass down styles in other calls to layout_prose + # QUESTION: should we pass down styles in other calls to layout_prose layout_prose term.text, margin_top: 0, margin_bottom: @theme.description_list_term_spacing, align: :left, line_height: term_line_height, normalize_line_height: true, styles: term_font_styles end end @@ -1351,7 +1351,7 @@ module Asciidoctor complex = node.compound? if (marker_type = @list_bullets[-1]) if marker_type == :checkbox - # QUESTION should we remove marker indent if not a checkbox? + # QUESTION: should we remove marker indent if not a checkbox? if node.attr? 'checkbox' marker_type = (node.attr? 'checked') ? :checked : :unchecked marker = @theme[%(ulist_marker_#{marker_type}_content)] || BallotBox[marker_type] @@ -1373,7 +1373,7 @@ module Asciidoctor marker_gap = rendered_width_of_char 'x' font marker_style[:font_family], size: marker_style[:font_size] do marker_width = rendered_width_of_string marker - # NOTE compensate if character_spacing is not applied to first character + # NOTE: compensate if character_spacing is not applied to first character # see https://github.com/prawnpdf/prawn/commit/c61c5d48841910aa11b9e3d6f0e01b68ce435329 character_spacing_correction = 0 character_spacing(-0.5) do @@ -1445,7 +1445,7 @@ module Asciidoctor end end # NOTE: import_page automatically advances to next page afterwards - # QUESTION should we add destination to top of imported page? + # QUESTION: should we add destination to top of imported page? if (pgnums = node.attr 'pages') (resolve_pagenums pgnums).each_with_index do |pgnum, idx| if idx == 0 @@ -1656,7 +1656,7 @@ module Asciidoctor end end - # QUESTION can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger? + # QUESTION: can we avoid arranging fragments multiple times (conums & autofit) by eagerly preparing arranger? def convert_listing_or_literal node add_dest_for_block node if node.id wrap_ext = source_chunks = bg_color_override = font_color_override = adjusted_font_size = nil @@ -1720,7 +1720,7 @@ module Asciidoctor source_chunks = conum_mapping ? (restore_conums fragments, conum_mapping) : fragments when 'pygments' style = (node.document.attr 'pygments-style') || 'pastie' - # QUESTION allow border color to be set by theme for highlighted block? + # QUESTION: allow border color to be set by theme for highlighted block? pg_block_styles = ::Pygments::Ext::BlockStyles.for style bg_color_override = pg_block_styles[:background_color] font_color_override = pg_block_styles[:font_color] @@ -1755,7 +1755,7 @@ module Asciidoctor end when 'rouge' formatter = (@rouge_formatter ||= ::Rouge::Formatters::Prawn.new theme: (node.document.attr 'rouge-style'), line_gap: @theme.code_line_gap, highlight_background_color: @theme.code_highlight_background_color) - # QUESTION allow border color to be set by theme for highlighted block? + # QUESTION: allow border color to be set by theme for highlighted block? bg_color_override = formatter.background_color if source_string.empty? source_chunks = [] @@ -1844,7 +1844,7 @@ module Asciidoctor '' end end - # NOTE use first position to store space that precedes conums + # NOTE: use first position to store space that precedes conums if (conum_mapping.key? line_num) && (line.end_with? ' ') trimmed_line = line.rstrip conum_mapping[line_num].unshift line.slice trimmed_line.length, line.length @@ -1859,8 +1859,8 @@ module Asciidoctor # Restore the conums into the Array of formatted text fragments #-- - # QUESTION can this be done more efficiently? - # QUESTION can we reuse arrange_fragments_by_line? + # QUESTION: can this be done more efficiently? + # QUESTION: can we reuse arrange_fragments_by_line? def restore_conums fragments, conum_mapping, linenums = nil, highlight_lines = nil lines = [] line_num = 0 @@ -1921,7 +1921,7 @@ module Asciidoctor theme = @theme tbl_bg_color = resolve_theme_color :table_background_color - # QUESTION should we fallback to page background color? (which is never transparent) + # QUESTION: should we fallback to page background color? (which is never transparent) #tbl_bg_color = resolve_theme_color :table_background_color, @page_bg_color # ...and if so, should we try to be helpful and use @page_bg_color for tables nested in blocks? #unless tbl_bg_color @@ -1954,7 +1954,7 @@ module Asciidoctor head_cell_padding = ::Array === head_cell_padding && head_cell_padding.size == 4 ? head_cell_padding.dup : (expand_padding_value head_cell_padding) head_cell_padding[0] += head_line_metrics.padding_top head_cell_padding[2] += head_line_metrics.padding_bottom - # QUESTION why doesn't text transform inherit from table? + # QUESTION: why doesn't text transform inherit from table? head_transform = resolve_text_transform :table_head_text_transform, nil base_cell_data = { inline_format: [normalize: true], @@ -2039,7 +2039,7 @@ module Asciidoctor cell_data[:content] = guard_indentation cell.instance_variable_get :@text # NOTE: the absence of the inline_format option implies it's disabled cell_data.delete :font_style - # QUESTION should we use literal_font_*, code_font_*, or introduce another category? + # QUESTION: should we use literal_font_*, code_font_*, or introduce another category? theme_font :code do literal_cell_font_info = font_info cell_data[:font] = literal_cell_font_info[:family] @@ -2171,7 +2171,7 @@ module Asciidoctor column_widths: column_widths, } - # QUESTION should we support nth; should we support sequence of roles? + # QUESTION: should we support nth; should we support sequence of roles? case node.attr 'stripes', nil, 'table-stripes' when 'all' table_settings[:row_colors] = [body_stripe_bg_color] @@ -2190,7 +2190,7 @@ module Asciidoctor # NOTE: call width to capture resolved table width table_width = width @pdf.layout_table_caption node, alignment, table_width, caption_max_width if node.title? && caption_side == :top - # NOTE align using padding instead of bounding_box as prawn-table does + # NOTE: align using padding instead of bounding_box as prawn-table does # using a bounding_box across pages mangles the margin box of subsequent pages if alignment != :left && table_width != (this_bounds = @pdf.bounds).width if alignment == :center @@ -2243,7 +2243,7 @@ module Asciidoctor end end - # QUESTION should cell padding be configurable for foot row cells? + # QUESTION: should cell padding be configurable for foot row cells? unless node.rows[:foot].empty? foot_row = row num_rows.pred foot_row.background_color = foot_bg_color @@ -2289,7 +2289,7 @@ module Asciidoctor nil end - # NOTE to insert sequential page breaks, you must put {nbsp} between page breaks + # NOTE: to insert sequential page breaks, you must put {nbsp} between page breaks def convert_page_break node if (page_layout = node.attr 'page-layout').nil_or_empty? unless node.role? && (page_layout = (node.roles.map(&:to_sym) & PageLayouts)[-1]) @@ -2315,7 +2315,7 @@ module Asciidoctor space_needed_for_category = @theme.description_list_term_spacing + (2 * (height_of_typeset_text 'A')) column_box [0, cursor], columns: (@theme.index_columns || 2), width: bounds.width, reflow_margins: true do @index.categories.each do |category| - # NOTE cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom + # NOTE: cursor method always returns 0 inside column_box; breaks reference_bounds.move_past_bottom bounds.move_past_bottom if space_needed_for_category > y - reference_bounds.absolute_bottom layout_prose category.name, align: :left, @@ -2373,20 +2373,20 @@ module Asciidoctor text = node.text end if (role = node.attr 'role') && (role == 'bare' || ((role.split ' ').include? 'bare')) - # QUESTION should we insert breakable chars into URI when building fragment instead? + # QUESTION: should we insert breakable chars into URI when building fragment instead? %(#{anchor}<a href="#{target}"#{attrs.join}>#{breakable_uri text}</a>) - # NOTE @media may not be initialized if method is called before convert phase + # NOTE: @media may not be initialized if method is called before convert phase elsif @media != 'screen' || (doc.attr? 'show-link-uri') - # QUESTION should we insert breakable chars into URI when building fragment instead? + # QUESTION: should we insert breakable chars into URI when building fragment instead? # TODO: allow style of printed link to be controlled by theme %(#{anchor}<a href="#{target}"#{attrs.join}>#{text}</a> [<font size="0.85em">#{breakable_uri bare_target}</font>]) else %(#{anchor}<a href="#{target}"#{attrs.join}>#{text}</a>) end when :xref - # NOTE non-nil path indicates this is an inter-document xref that's not included in current document + # NOTE: non-nil path indicates this is an inter-document xref that's not included in current document if (path = node.attributes['path']) - # NOTE we don't use local as that doesn't work on the web + # NOTE: we don't use local as that doesn't work on the web %(<a href="#{target}">#{node.text || path}</a>) elsif (refid = node.attributes['refid']) unless (text = node.text) @@ -2400,11 +2400,11 @@ module Asciidoctor %(<a anchor="#{doc.attr 'pdf-anchor'}">#{node.text || '[^top]'}</a>) end when :ref - # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment + # NOTE: destination is created inside callback registered by FormattedTextTransform#build_fragment %(<a id="#{node.id}">#{DummyText}</a>) when :bibref - # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment - # NOTE technically node.text should be node.reftext, but subs have already been applied to text + # NOTE: destination is created inside callback registered by FormattedTextTransform#build_fragment + # NOTE: technically node.text should be node.reftext, but subs have already been applied to text reftext = (reftext = node.reftext) ? %([#{reftext}]) : %([#{node.id}]) %(<a id="#{node.id}">#{DummyText}</a>#{reftext}) else @@ -2427,7 +2427,7 @@ module Asciidoctor result = conum_glyph node.text.to_i end if (conum_font_color = @theme.conum_font_color) - # NOTE CMYK value gets flattened here, but is restored by formatted text parser + # NOTE: CMYK value gets flattened here, but is restored by formatted text parser result = %(<color rgb="#{conum_font_color}">#{result}</font>) end result @@ -2443,7 +2443,7 @@ module Asciidoctor end %(#{anchor}<sup>[<a anchor="_footnotedef_#{index}">#{label}</a>]</sup>) elsif node.type == :xref - # NOTE footnote reference not found + # NOTE: footnote reference not found %(<sup><color rgb="FF0000">[#{node.text}]</color></sup>) end end @@ -2516,7 +2516,7 @@ module Asciidoctor if image_format == 'gif' && !(defined? ::GMagick::Image) log :warn, %(GIF image format not supported. Install the prawn-gmagick gem or convert #{target} to PNG.) img = %([#{node.attr 'alt'}]) - # NOTE an image with a data URI is handled using a temporary file + # NOTE: an image with a data URI is handled using a temporary file elsif (image_path = resolve_image_path node, target, image_format) if ::File.readable? image_path width_attr = (width = resolve_explicit_width node.attributes) ? %( width="#{width}") : '' @@ -2537,9 +2537,9 @@ module Asciidoctor if scratch? node.type == :visible ? node.text : '' else - # NOTE initialize index in case converter is called before PDF is initialized + # NOTE: initialize index in case converter is called before PDF is initialized @index ||= IndexCatalog.new - # NOTE page number (:page key) is added by InlineDestinationMarker + # NOTE: page number (:page key) is added by InlineDestinationMarker dest = { anchor: (anchor_name = @index.next_anchor_name) } anchor = %(<a id="#{anchor_name}" type="indexterm">#{DummyText}</a>) if node.type == :visible @@ -2606,14 +2606,14 @@ module Asciidoctor quoted_text = %(#{open}#{inner_text}#{close}) end - # NOTE destination is created inside callback registered by FormattedTextTransform#build_fragment + # NOTE: destination is created inside callback registered by FormattedTextTransform#build_fragment node.id ? %(<a id="#{node.id}">#{DummyText}</a>#{quoted_text}) : quoted_text end def layout_title_page doc return unless doc.header? && !doc.notitle - # NOTE a new page may have already been started at this point, so decide what to do with it + # NOTE: a new page may have already been started at this point, so decide what to do with it if page.empty? page.reset_content if (recycle = @ppbook ? recto_page? : true) elsif @ppbook && page_number > 0 && recto_page? @@ -2633,10 +2633,10 @@ module Asciidoctor @page_bg_image[side] = prev_bg_image if bg_image @page_bg_color = prev_bg_color if bg_color - # IMPORTANT this is the first page created, so we need to set the base font + # NOTE: this is the first page created, so we must set the base font font @theme.base_font_family, size: @root_font_size - # QUESTION allow alignment per element on title page? + # QUESTION: allow alignment per element on title page? title_align = (@theme.title_page_align || @base_align).to_sym # FIXME: disallow .pdf as image type @@ -2660,14 +2660,14 @@ module Asciidoctor end end logo_image_attrs['target'] = logo_image_path - # NOTE at the very least, title_align will be a valid alignment value + # NOTE: at the very least, title_align will be a valid alignment value logo_image_attrs['align'] = [(logo_image_attrs.delete 'align'), @theme.title_page_logo_align, title_align.to_s].find {|val| (BlockAlignmentNames.include? val) } if (logo_image_top = logo_image_attrs['top'] || @theme.title_page_logo_top) initial_y, @y = @y, (resolve_top logo_image_top) end # FIXME: add API to Asciidoctor for creating blocks like this (extract from extensions module?) image_block = ::Asciidoctor::Block.new doc, :image, content_model: :empty, attributes: logo_image_attrs - # NOTE pinned option keeps image on same page + # NOTE: pinned option keeps image on same page indent (@theme.title_page_logo_margin_left || 0), (@theme.title_page_logo_margin_right || 0) do convert_image image_block, relative_to_imagesdir: relative_to_imagesdir, pinned: true end @@ -2761,7 +2761,7 @@ module Asciidoctor if image_path.empty? go_to_page page_count if face == :back start_new_page_discretely - # NOTE open graphics state to prevent page from being reused + # NOTE: open graphics state to prevent page from being reused open_graphics_state if face == :front return elsif image_path == '~' @@ -2809,8 +2809,8 @@ module Asciidoctor alias layout_part_title layout_chapter_title - # NOTE layout_heading doesn't set the theme font because it's used for various types of headings - # QUESTION why doesn't layout_heading accept a node? + # NOTE: layout_heading doesn't set the theme font because it's used for various types of headings + # QUESTION: why doesn't layout_heading accept a node? def layout_heading string, opts = {} hlevel = opts[:level] unless (top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top)) @@ -2829,7 +2829,7 @@ module Asciidoctor end outdent_section opts.delete :outdent do margin_top top_margin - # QUESTION should we move inherited styles to typeset_text? + # QUESTION: should we move inherited styles to typeset_text? if (inherited = apply_text_decoration font_styles, :heading, hlevel).empty? inline_format_opts = true else @@ -2844,7 +2844,7 @@ module Asciidoctor end end - # NOTE inline_format is true by default + # NOTE: inline_format is true by default def layout_prose string, opts = {} top_margin = (margin = (opts.delete :margin)) || (opts.delete :margin_top) || @theme.prose_margin_top bot_margin = margin || (opts.delete :margin_bottom) || @theme.prose_margin_bottom @@ -2852,12 +2852,12 @@ module Asciidoctor string = transform_text string, transform end string = hyphenate_text string, @hyphenator if (opts.delete :hyphenate) && (defined? @hyphenator) - # NOTE used by extensions; ensures linked text gets formatted using the link styles + # NOTE: used by extensions; ensures linked text gets formatted using the link styles if (anchor = opts.delete :anchor) string = %(<a anchor="#{anchor}">#{string}</a>) end margin_top top_margin - # NOTE normalize makes endlines soft (replaces "\n" with ' ') + # NOTE: normalize makes endlines soft (replaces "\n" with ' ') inline_format_opts = { normalize: (opts.delete :normalize) != false } if (styles = opts.delete :styles) inline_format_opts[:inherited] = { @@ -2978,7 +2978,7 @@ module Asciidoctor end end end - # NOTE we assume we don't clear more than one page + # NOTE: we assume we don't clear more than one page if page_number > mark[:page_number] mark[:cursor] + (bounds.top - cursor) else @@ -2999,7 +2999,7 @@ module Asciidoctor move_down @theme.block_margin_bottom unless use_title_page toc_end = @y end - # NOTE reserve pages for the toc; leaves cursor on page after last page in toc + # NOTE: reserve pages for the toc; leaves cursor on page after last page in toc if use_title_page toc_page_nums.each { start_new_page } else @@ -3009,7 +3009,7 @@ module Asciidoctor @toc_extent = { page_nums: toc_page_nums, start_y: toc_start_y } end - # NOTE num_front_matter_pages is not used during a dry run + # NOTE: num_front_matter_pages is not used during a dry run def layout_toc doc, num_levels = 2, toc_page_number = 2, start_y = @y, num_front_matter_pages = 0 go_to_page toc_page_number unless (page_number == toc_page_number) || scratch? start_page_number = page_number @@ -3022,7 +3022,7 @@ module Asciidoctor end end end - # QUESTION should we skip this whole method if num_levels < 0? + # QUESTION: should we skip this whole method if num_levels < 0? unless num_levels < 0 dot_leader = theme_font :toc do # TODO: we could simplify by using nested theme_font :toc_dot_leader @@ -3045,14 +3045,14 @@ module Asciidoctor theme_margin :toc, :top layout_toc_level doc.sections, num_levels, line_metrics, dot_leader, num_front_matter_pages end - # NOTE range must be calculated relative to toc_page_number; absolute page number in scratch document is arbitrary + # NOTE: range must be calculated relative to toc_page_number; absolute page number in scratch document is arbitrary toc_page_numbers = (toc_page_number..(toc_page_number + (page_number - start_page_number))) go_to_page page_count unless scratch? toc_page_numbers end def layout_toc_level sections, num_levels, line_metrics, dot_leader, num_front_matter_pages = 0 - # NOTE font options aren't always reliable, so store size separately + # NOTE: font options aren't always reliable, so store size separately toc_font_info = theme_font :toc do { font: font, size: @font_size } end @@ -3062,11 +3062,11 @@ module Asciidoctor theme_font :toc, level: (sect.level + 1) do sect_title = @text_transform ? (transform_text sect.numbered_title, @text_transform) : sect.numbered_title pgnum_label_placeholder_width = rendered_width_of_string '0' * @toc_max_pagenum_digits - # NOTE only write section title (excluding dots and page number) if this is a dry run + # NOTE: only write section title (excluding dots and page number) if this is a dry run if scratch? indent 0, pgnum_label_placeholder_width do # FIXME: use layout_prose - # NOTE must wrap title in empty anchor element in case links are styled with different font family / size + # NOTE: must wrap title in empty anchor element in case links are styled with different font family / size typeset_text %(<a>#{sect_title}</a>), line_metrics, inline_format: true, hanging_indent: hanging_indent, normalize_line_height: true end else @@ -3077,7 +3077,7 @@ module Asciidoctor start_cursor = cursor start_dots = nil sect_title_inherited = (apply_text_decoration ::Set.new, :toc, sect.level.next).merge anchor: (sect_anchor = sect.attr 'pdf-anchor'), color: @font_color - # NOTE use text formatter to add anchor overlay to avoid using inline format with synthetic anchor tag + # NOTE: use text formatter to add anchor overlay to avoid using inline format with synthetic anchor tag sect_title_fragments = text_formatter.format sect_title, inherited: sect_title_inherited indent 0, pgnum_label_placeholder_width do sect_title_fragments[-1][:callback] = (last_fragment_pos = ::Asciidoctor::PDF::FormattedText::FragmentPositionRenderer.new) @@ -3093,7 +3093,7 @@ module Asciidoctor pgnum_label_width = rendered_width_of_string pgnum_label pgnum_label_font_settings = { color: @font_color, font: font_family, size: @font_size, styles: font_styles } save_font do - # NOTE the same font is used for dot leaders throughout toc + # NOTE: the same font is used for dot leaders throughout toc set_font toc_font_info[:font], toc_font_info[:size] font_style dot_leader[:font_style] num_dots = [((bounds.width - start_dots - dot_leader[:spacer_width] - pgnum_label_width) / dot_leader[:width]).floor, 0].max @@ -3142,7 +3142,7 @@ module Asciidoctor # TODO: delegate to layout_page_header and layout_page_footer per page def layout_running_content periphery, doc, skip = [1, 1], body_start_page_number = 1 skip_pages, skip_pagenums = skip - # NOTE find and advance to first non-imported content page to use as model page + # NOTE: find and advance to first non-imported content page to use as model page return unless (content_start_page = state.pages[skip_pages..-1].index {|it| !it.imported_page? }) content_start_page += (skip_pages + 1) num_pages = page_count @@ -3185,9 +3185,9 @@ module Asciidoctor parts_by_page = SectionInfoByPage.new title_method chapters_by_page = SectionInfoByPage.new title_method sections_by_page = SectionInfoByPage.new title_method - # QUESTION should the default part be the doctitle? + # QUESTION: should the default part be the doctitle? last_part = nil - # QUESTION should we enforce that the preamble is a preface? + # QUESTION: should we enforce that the preamble is a preface? last_chap = is_book ? :pre : nil last_sect = nil sect_search_threshold = 1 @@ -3205,7 +3205,7 @@ module Asciidoctor last_sect = sect elsif part || chap sect_search_threshold = pgnum - # NOTE we didn't find a section on this page; look back to find last section started + # NOTE: we didn't find a section on this page; look back to find last section started elsif last_sect (sect_search_threshold..(pgnum - 1)).reverse_each do |prev| if (sect = trailing_section_start_pages[prev]) @@ -3234,7 +3234,7 @@ module Asciidoctor end doctitle = doc.doctitle partition: true, use_fallback: true - # NOTE set doctitle again so it's properly escaped + # NOTE: set doctitle again so it's properly escaped doc.set_attr 'doctitle', doctitle.combined doc.set_attr 'document-title', doctitle.main doc.set_attr 'document-subtitle', doctitle.subtitle @@ -3269,7 +3269,7 @@ module Asciidoctor content_by_position, colspec_by_position = content_dict[side], colspec_dict[side] doc.set_attr 'page-number', pgnum_label if pagenums_enabled - # QUESTION should the fallback value be nil instead of empty string? or should we remove attribute if no value? + # QUESTION: should the fallback value be nil instead of empty string? or should we remove attribute if no value? doc.set_attr 'part-title', ((part_info = parts_by_page[pgnum])[:title] || '') if (part_numeral = part_info[:numeral]) doc.set_attr 'part-numeral', part_numeral @@ -3310,11 +3310,11 @@ module Asciidoctor end # FIXME: we need to have a content setting for chapter pages if ::Array === content - # NOTE float ensures cursor position is restored and returns us to current page if we overrun + # NOTE: float ensures cursor position is restored and returns us to current page if we overrun float do - # NOTE bounding_box is redundant if both vertical padding and border width are 0 + # NOTE: bounding_box is redundant if both vertical padding and border width are 0 bounding_box [left, bounds.top - trim_styles[:padding][side][0] - trim_styles[:content_offset]], width: colwidth, height: trim_styles[:content_height][side] do - # NOTE image vposition respects padding; use negative image_vertical_align value to revert + # NOTE: image vposition respects padding; use negative image_vertical_align value to revert image_opts = content[1].merge position: colspec[:align], vposition: trim_styles[:img_valign] begin image_info = image content[0], image_opts @@ -3329,7 +3329,7 @@ module Asciidoctor end else theme_font %(#{periphery}_#{side}_#{position}) do - # NOTE minor optimization + # NOTE: minor optimization if content == '{page-number}' content = pagenums_enabled ? pgnum_label : nil else @@ -3389,7 +3389,7 @@ module Asciidoctor end trim_styles = { line_metrics: (trim_line_metrics = calc_line_metrics @theme[%(#{periphery}_line_height)] || @theme.base_line_height), - # NOTE we've already verified this property is set + # NOTE: we've already verified this property is set height: (trim_height = @theme[%(#{periphery}_height)]), bg_color: (resolve_theme_color %(#{periphery}_background_color).to_sym), border_color: (trim_border_color = resolve_theme_color %(#{periphery}_border_color).to_sym), @@ -3433,7 +3433,7 @@ module Asciidoctor recto: trim_content_height[:recto] - trim_line_metrics.padding_top - trim_line_metrics.padding_bottom, verso: trim_content_height[:verso] - trim_line_metrics.padding_top - trim_line_metrics.padding_bottom, }, - # NOTE content offset adjusts y position to account for border + # NOTE: content offset adjusts y position to account for border content_offset: (periphery == :footer ? trim_border_width * 0.5 : 0), } case trim_styles[:img_valign] @@ -3477,7 +3477,7 @@ module Asciidoctor tot_width += rel_width [col, { align: alignment, width: rel_width, x: 0 }] }.to_h - # QUESTION should we allow the columns to overlap (capping width at 100%)? + # QUESTION: should we allow the columns to overlap (capping width at 100%)? side_colspecs.each {|_, colspec| colspec[:width] = (colspec[:width] / tot_width) * side_trim_content_width } side_colspecs[:right][:x] = (side_colspecs[:center][:x] = side_colspecs[:left][:width]) + side_colspecs[:center][:width] acc[side] = side_colspecs @@ -3503,7 +3503,7 @@ module Asciidoctor image_opts = resolve_image_options image_path, image_format, image_attrs, container_size: [colspec_dict[side][position][:width], trim_content_height[side]] side_content[position] = [image_path, image_opts, image_attrs['link']] else - # NOTE allows inline image handler to report invalid reference and replace with alt text + # NOTE: allows inline image handler to report invalid reference and replace with alt text side_content[position] = %(image:#{image_path}[#{attrlist}]) end else @@ -3568,7 +3568,7 @@ module Asciidoctor if document.page_count >= initial_pagenum && (doctitle = doc.header? ? doc.doctitle : (doc.attr 'untitled-label')) page title: (document.sanitize doctitle), destination: (document.dest_top has_front_cover ? 2 : 1) end - # QUESTION is there any way to get add_outline_level to invoke in the context of the outline? + # QUESTION: is there any way to get add_outline_level to invoke in the context of the outline? document.add_outline_level self, doc.sections, num_levels, expand_levels end if doc.attr? 'outline' @@ -3625,7 +3625,7 @@ module Asciidoctor pdf_doc.render target else pdf_doc.render_file target - # QUESTION restore attributes first? + # QUESTION: restore attributes first? @pdfmark&.generate_file target (Optimizer.new @optimize, pdf_doc.min_version).generate_file target if @optimize && ((defined? ::Asciidoctor::PDF::Optimizer) || !(Helpers.require_library OptimizerRequirePath, 'rghost', :warn).nil?) to_file = true @@ -3689,8 +3689,8 @@ module Asciidoctor end end - # QUESTION should we pass a category as an argument? - # QUESTION should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback) + # QUESTION: should we pass a category as an argument? + # QUESTION: should we make this a method on the theme ostruct? (e.g., @theme.resolve_color key, fallback) def resolve_theme_color key, fallback_color = nil if (color = @theme[key.to_s]) && color != 'transparent' color @@ -3751,7 +3751,7 @@ module Asciidoctor chunk_height = [(available_height = cursor), remaining_height].min bounding_box [0, available_height], width: bounds.width, height: chunk_height do theme_fill_and_stroke_bounds category, background_color: bg_color - # NOTE b_width is always set; if no border is set, split indicator is cut into background + # NOTE: b_width is always set; if no border is set, split indicator is cut into background indent b_radius, b_radius do # dashed line indicates continuation from previous page; swell line slightly to cover background stroke_horizontal_rule b_gap_color, line_width: b_width * 1.2, line_style: :dashed, at: b_shift @@ -3789,7 +3789,7 @@ module Asciidoctor # the page. def margin amount, _side unless (amount || 0) == 0 || at_page_top? - # NOTE use low-level cursor calculation to workaround cursor bug in column_box context + # NOTE: use low-level cursor calculation to workaround cursor bug in column_box context if y - reference_bounds.absolute_bottom > amount move_down amount else @@ -3817,7 +3817,7 @@ module Asciidoctor style = @theme[%(#{hlevel_category}_font_style)] || @theme[%(#{category}_font_style)] color = @theme[%(#{hlevel_category}_font_color)] || @theme[%(#{category}_font_color)] kerning = resolve_font_kerning @theme[%(#{hlevel_category}_font_kerning)] || @theme[%(#{category}_font_kerning)] - # NOTE global text_transform is not currently supported + # NOTE: global text_transform is not currently supported transform = @theme[%(#{hlevel_category}_text_transform)] || @theme[%(#{category}_text_transform)] else inherited_font = font_info @@ -3826,7 +3826,7 @@ module Asciidoctor style = @theme[%(#{category}_font_style)] || inherited_font[:style] color = @theme[%(#{category}_font_color)] kerning = resolve_font_kerning @theme[%(#{category}_font_kerning)] - # NOTE global text_transform is not currently supported + # NOTE: global text_transform is not currently supported transform = @theme[%(#{category}_text_transform)] end @@ -3851,8 +3851,8 @@ module Asciidoctor # font size adjustment is necessary. def compute_autofit_font_size fragments, category arranger = arrange_fragments_by_line fragments - # NOTE finalizing the line here generates fragments & calculates their widths using the current font settings - # CAUTION it also removes zero-width spaces + # NOTE: finalizing the line here generates fragments & calculates their widths using the current font settings + # NOTE: it also removes zero-width spaces arranger.finalize_line actual_width = width_of_fragments arranger.fragments unless ::Array === (padding = @theme[%(#{category}_padding)]) @@ -3949,7 +3949,7 @@ module Asciidoctor move_down line_metrics.padding_bottom end - # QUESTION combine with typeset_text? + # QUESTION: combine with typeset_text? def typeset_formatted_text fragments, line_metrics, opts = {} move_down line_metrics.padding_top opts = { leading: line_metrics.leading, final_gap: line_metrics.final_gap }.merge opts @@ -3968,7 +3968,7 @@ module Asciidoctor (height_of string, leading: line_metrics.leading, final_gap: line_metrics.final_gap) + line_metrics.padding_top + (opts[:single_line] ? 0 : line_metrics.padding_bottom) end - # NOTE only used when tabsize attribute is not specified + # NOTE: only used when tabsize attribute is not specified # tabs must always be replaced with spaces in order for the indentation guards to work def expand_tabs string if string.nil_or_empty? @@ -4067,7 +4067,7 @@ module Asciidoctor def add_dest_for_block node, id = nil if !scratch? && (id ||= node.id) dest_x = bounds.absolute_left.truncate 4 - # QUESTION when content is aligned to left margin, should we keep precise x value or just use 0? + # QUESTION: when content is aligned to left margin, should we keep precise x value or just use 0? dest_x = 0 if dest_x <= page_margin_left dest_y = at_page_top? && (node.context == :section || node.context == :document) ? page_height : y # TODO: find a way to store only the ref of the destination; look it up when we need it @@ -4083,7 +4083,7 @@ module Asciidoctor end end - # QUESTION is this method still necessary? + # QUESTION: is this method still necessary? def resolve_imagesdir doc if (imagesdir = doc.attr 'imagesdir').nil_or_empty? || (imagesdir = imagesdir.chomp '/') == '.' nil @@ -4108,7 +4108,7 @@ module Asciidoctor def resolve_image_path node, image_path, image_format, relative_to = true doc = node.document imagesdir = relative_to == true ? (resolve_imagesdir doc) : relative_to - # NOTE base64 logic currently used for inline images + # NOTE: base64 logic currently used for inline images if ::Base64 === image_path return @tmp_files[image_path] if @tmp_files.key? image_path tmp_image = ::Tempfile.create ['image-', %(.#{image_format})] @@ -4226,7 +4226,7 @@ module Asciidoctor image_opts[:width] = image_width end when 'scale-down' - # NOTE if width and height aren't set in SVG, real width and height are computed after stretching viewbox to fit page + # NOTE: if width and height aren't set in SVG, real width and height are computed after stretching viewbox to fit page if (image_width = resolve_explicit_width image_attrs, bounds_width: container_width) if image_width > container_width image_opts[:fit] = container_size @@ -4243,7 +4243,7 @@ module Asciidoctor image_opts[:fit] = container_size if (to_pt image_size[:width], :px) > container_width || (to_pt image_size[:height], :px) > container_height end when 'cover' - # QUESTION should we take explicit width into account? + # QUESTION: should we take explicit width into account? image_size = intrinsic_image_dimensions image_path, image_format if container_width * (image_size[:height].to_f / image_size[:width]) < container_height image_opts[:height] = container_height @@ -4276,10 +4276,10 @@ module Asciidoctor # bounds_width option is given, the percentage of the bounds_width value is returned. # Otherwise, the percentage width is returned. #-- - # QUESTION should we enforce positive result? + # QUESTION: should we enforce positive result? def resolve_explicit_width attrs, opts = {} bounds_width = opts[:bounds_width] - # QUESTION should we restrict width to bounds_width for pdfwidth? + # QUESTION: should we restrict width to bounds_width for pdfwidth? if attrs.key? 'pdfwidth' if (width = attrs['pdfwidth']).end_with? '%' bounds_width ? (width.to_f / 100) * bounds_width : width @@ -4289,7 +4289,7 @@ module Asciidoctor str_to_pt width end elsif attrs.key? 'scaledwidth' - # NOTE the parser automatically appends % if value is unitless + # NOTE: the parser automatically appends % if value is unitless if (width = attrs['scaledwidth']).end_with? '%' bounds_width ? (width.to_f / 100) * bounds_width : width else @@ -4438,7 +4438,7 @@ module Asciidoctor accum[name] = doc.attr name if (val = doc.attr %(#{name}_#{idx})) doc.set_attr name, val - # NOTE email holds url as well + # NOTE: email holds url as well email = val if name == 'email' else doc.remove_attr name @@ -4461,13 +4461,13 @@ module Asciidoctor result end - # NOTE assume URL is escaped (i.e., contains character references such as &) + # NOTE: assume URL is escaped (i.e., contains character references such as &) def breakable_uri uri scheme, address = uri.split UriSchemeBoundaryRx, 2 address, scheme = scheme, address unless address unless address.nil_or_empty? address = address.gsub UriBreakCharsRx, UriBreakCharRepl - # NOTE require at least two characters after a break + # NOTE: require at least two characters after a break address.slice!(-2) if address[-2] == ZeroWidthSpace end %(#{scheme}#{address}) @@ -4507,17 +4507,17 @@ module Asciidoctor (code.start_with? '\u') ? ([((code.slice 2, code.length).to_i 16)].pack 'U1') : code end - # QUESTION move to prawn/extensions.rb? + # QUESTION: move to prawn/extensions.rb? def init_scratch_prototype @save_state = nil @scratch_depth = 0 - # NOTE don't need background image in scratch document; can cause marshal error anyway + # NOTE: don't need background image in scratch document; can cause marshal error anyway saved_page_bg_image, @page_bg_image = @page_bg_image, { verso: nil, recto: nil } - # IMPORTANT don't set font before using Marshal, it causes serialization to fail + # NOTE: don't set font before using Marshal as it causes serialization to fail @prototype = ::Marshal.load ::Marshal.dump self @page_bg_image = saved_page_bg_image @prototype.state.store.info.data[:Scratch] = @prototype.text_formatter.scratch = true - # NOTE we're now starting a new page each time, so no need to do it here + # NOTE: we're now starting a new page each time, so no need to do it here #@prototype.start_new_page if @prototype.page_number == 0 end diff --git a/lib/asciidoctor/pdf/ext/asciidoctor.rb b/lib/asciidoctor/pdf/ext/asciidoctor.rb index 46ea190c..7cbc6aad 100644 --- a/lib/asciidoctor/pdf/ext/asciidoctor.rb +++ b/lib/asciidoctor/pdf/ext/asciidoctor.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -# NOTE these are either candidates for inclusion in Asciidoctor core or backports +# NOTE: these are either candidates for inclusion in Asciidoctor core or backports require_relative 'asciidoctor/abstract_block' require_relative 'asciidoctor/section' require_relative 'asciidoctor/list' diff --git a/lib/asciidoctor/pdf/ext/core/file.rb b/lib/asciidoctor/pdf/ext/core/file.rb index 23c2b58f..70199e8e 100644 --- a/lib/asciidoctor/pdf/ext/core/file.rb +++ b/lib/asciidoctor/pdf/ext/core/file.rb @@ -2,7 +2,7 @@ class File class << self - # NOTE remove once minimum required Ruby version is at least 2.7 + # NOTE: remove once minimum required Ruby version is at least 2.7 def absolute_path? path (path.start_with? '/') || (ALT_SEPARATOR && (path.start_with? (absolute_path path).slice 0, 3)) end unless method_defined? :absolute_path? diff --git a/lib/asciidoctor/pdf/ext/pdf-core/page.rb b/lib/asciidoctor/pdf/ext/pdf-core/page.rb index 55712452..eb639d1e 100644 --- a/lib/asciidoctor/pdf/ext/pdf-core/page.rb +++ b/lib/asciidoctor/pdf/ext/pdf-core/page.rb @@ -18,7 +18,7 @@ class PDF::Core::Page document.open_graphics_state end unless method_defined? :new_content_stream - # NOTE alias method to avoid warning if another gem replaces this method + # NOTE: alias method to avoid warning if another gem replaces this method alias __new_content_stream new_content_stream # Restore the imported_page? method from PDF::Core::Page diff --git a/lib/asciidoctor/pdf/ext/prawn-svg.rb b/lib/asciidoctor/pdf/ext/prawn-svg.rb index 042ba799..a82228dd 100644 --- a/lib/asciidoctor/pdf/ext/prawn-svg.rb +++ b/lib/asciidoctor/pdf/ext/prawn-svg.rb @@ -4,5 +4,5 @@ require 'prawn-svg' unless defined? Prawn::SVG::Interface require_relative 'prawn-svg/interface' require_relative 'prawn-svg/loaders/web' require_relative 'prawn-svg/url_loader' -# NOTE disable system fonts since they're non-portable +# NOTE: disable system fonts since they're non-portable Prawn::SVG::Interface.font_path.clear diff --git a/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb b/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb index 58be7c45..390622cb 100644 --- a/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb +++ b/lib/asciidoctor/pdf/ext/prawn-table/cell/asciidoc.rb @@ -54,27 +54,27 @@ module Prawn end def natural_content_width - # QUESTION can we get a better estimate of the natural width? + # QUESTION: can we get a better estimate of the natural width? @natural_content_width ||= (@pdf.bounds.width - padding_left - padding_right) end def natural_content_height - # NOTE when natural_content_height is called, we already know max width + # NOTE: when natural_content_height is called, we already know max width @natural_content_height ||= dry_run end def draw_content pdf = @pdf - # NOTE draw_bounded_content automatically adds FPTolerance to width and height + # NOTE: draw_bounded_content automatically adds FPTolerance to width and height pdf.bounds.instance_variable_set :@width, spanned_content_width - # NOTE we've already reserved the space, so just let the box stretch to the bottom of the page to avoid overflow + # NOTE: we've already reserved the space, so just let the box stretch to the bottom of the page to avoid overflow pdf.bounds.instance_variable_set :@height, pdf.page_content_height if @valign != :top && (excess_y = spanned_content_height - natural_content_height) > 0 pdf.move_down(@valign == :center ? (excess_y.fdiv 2) : excess_y) end start_page = pdf.page_number # TODO: apply horizontal alignment (right now must use alignment on content block) - # QUESTION inherit table cell font properties? + # QUESTION: inherit table cell font properties? apply_font_properties do pdf.traverse content end @@ -89,7 +89,7 @@ module Prawn private def apply_font_properties - # NOTE font_info holds font properties outside table; used as fallback values + # NOTE: font_info holds font properties outside table; used as fallback values font_info = (pdf = @pdf).font_info font_color, font_family, font_size, font_style = @font_options.values_at :color, :family, :size, :style prev_font_color, pdf.font_color = pdf.font_color, font_color if font_color diff --git a/lib/asciidoctor/pdf/ext/prawn-templates.rb b/lib/asciidoctor/pdf/ext/prawn-templates.rb index 66de1974..4a1b3824 100644 --- a/lib/asciidoctor/pdf/ext/prawn-templates.rb +++ b/lib/asciidoctor/pdf/ext/prawn-templates.rb @@ -1,7 +1,7 @@ # frozen_string_literal: true class Prawn::Document - # NOTE allows prawn-templates 0.0.4 to be used with prawn >= 2.2.0 + # NOTE: allows prawn-templates 0.0.4 to be used with prawn >= 2.2.0 const_set :VALID_OPTIONS, (send :remove_const, :VALID_OPTIONS).dup if VALID_OPTIONS.frozen? end require 'prawn/templates' diff --git a/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb b/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb index 25378899..9b410f9c 100644 --- a/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb +++ b/lib/asciidoctor/pdf/ext/prawn/coderay_encoder.rb @@ -80,7 +80,7 @@ module Asciidoctor super @out = [] @open = [] - # NOTE tracks whether text token begins at the start of a line + # NOTE: tracks whether text token begins at the start of a line @start_of_line = true end @@ -88,17 +88,17 @@ module Asciidoctor if text == LF @out << { text: text } @start_of_line = true - # NOTE text is nil and kind is :error when CodeRay ends parsing on an error + # NOTE: text is nil and kind is :error when CodeRay ends parsing on an error elsif text - # NOTE add guard character to prevent Prawn from trimming indentation + # NOTE: add guard character to prevent Prawn from trimming indentation text[0] = GuardedIndent if @start_of_line && (text.start_with? ' ') text.gsub! InnerIndent, GuardedInnerIndent if text.include? InnerIndent - # NOTE this optimization assumes we don't support/use background colors + # NOTE: this optimization assumes we don't support/use background colors if text.rstrip.empty? @out << { text: text } else - # QUESTION should we default to no color? + # QUESTION: should we default to no color? @out << { text: text, color: (COLORS[kind] || COLORS[@open[-1]] || COLORS[:default]) } end @start_of_line = text.end_with? LF diff --git a/lib/asciidoctor/pdf/ext/prawn/extensions.rb b/lib/asciidoctor/pdf/ext/prawn/extensions.rb index e7359ea0..723262cb 100644 --- a/lib/asciidoctor/pdf/ext/prawn/extensions.rb +++ b/lib/asciidoctor/pdf/ext/prawn/extensions.rb @@ -22,7 +22,7 @@ module Asciidoctor italic: [:italic].to_set, bold_italic: [:bold, :italic].to_set, }).default = ::Set.new - # NOTE must use a visible char for placeholder or else Prawn won't reserve space for the fragment + # NOTE: must use a visible char for placeholder or else Prawn won't reserve space for the fragment PlaceholderChar = ?\u2063 # - :height is the height of a line @@ -245,7 +245,7 @@ module Asciidoctor # implementation to carry out the built-in functionality. # #-- - # QUESTION should we round the result? + # QUESTION: should we round the result? def font_size points = nil return @font_size unless points if points == 1 @@ -371,7 +371,7 @@ module Asciidoctor end end - # NOTE override built-in fill_formatted_text_box to insert leading before second line when :first_line is true + # NOTE: override built-in fill_formatted_text_box to insert leading before second line when :first_line is true def fill_formatted_text_box text, opts merge_text_box_positioning_options opts box = ::Prawn::Text::Formatted::Box.new text, opts @@ -388,7 +388,7 @@ module Asciidoctor remaining_text end - # NOTE override built-in draw_indented_formatted_line to set first_line flag + # NOTE: override built-in draw_indented_formatted_line to set first_line flag def draw_indented_formatted_line string, opts super string, (opts.merge first_line: true) end @@ -399,7 +399,7 @@ module Asciidoctor def text_with_formatted_first_line string, first_line_opts, opts color = opts.delete :color fragments = parse_text string, opts - # NOTE the low-level APIs we're using don't recognize the :styles option, so we must resolve + # NOTE: the low-level APIs we're using don't recognize the :styles option, so we must resolve if (styles = opts.delete :styles) opts[:style] = resolve_font_style styles end @@ -408,10 +408,10 @@ module Asciidoctor end first_line_color = (first_line_opts.delete :color) || color opts = opts.merge document: self - # QUESTION should we merge more carefully here? (hand-select keys?) + # QUESTION: should we merge more carefully here? (hand-select keys?) first_line_opts = opts.merge(first_line_opts).merge single_line: true, first_line: true box = ::Prawn::Text::Formatted::Box.new fragments, first_line_opts - # NOTE get remaining_fragments before we add color to fragments on first line + # NOTE: get remaining_fragments before we add color to fragments on first line if (text_indent = opts.delete :indent_paragraphs) remaining_fragments = indent text_indent do box.render dry_run: true @@ -419,7 +419,7 @@ module Asciidoctor else remaining_fragments = box.render dry_run: true end - # NOTE color must be applied per-fragment + # NOTE: color must be applied per-fragment fragments.each {|fragment| fragment[:color] ||= first_line_color } if first_line_color if text_indent indent text_indent do @@ -429,7 +429,7 @@ module Asciidoctor fill_formatted_text_box fragments, first_line_opts end unless remaining_fragments.empty? - # NOTE color must be applied per-fragment + # NOTE: color must be applied per-fragment remaining_fragments.each {|fragment| fragment[:color] ||= color } if color remaining_fragments = fill_formatted_text_box remaining_fragments, opts draw_remaining_formatted_text_on_new_pages remaining_fragments, opts @@ -473,7 +473,7 @@ module Asciidoctor # Override built-in move_text_position method to prevent Prawn from advancing # to next page if image doesn't fit before rendering image. #-- - # NOTE could use :at option when calling image/embed_image instead + # NOTE: could use :at option when calling image/embed_image instead def move_text_position h; end # Short-circuits the call to the built-in move_down operation @@ -526,9 +526,9 @@ module Asciidoctor bounds.add_left_padding p_left bounds.add_right_padding p_right yield - # NOTE support negative bottom padding for use with quote block + # NOTE: support negative bottom padding for use with quote block if p_bottom < 0 - # QUESTION should we return to previous page if top of page is reached? + # QUESTION: should we return to previous page if top of page is reached? p_bottom < cursor - reference_bounds.top ? (move_cursor_to reference_bounds.top) : (move_down p_bottom) else p_bottom < cursor ? (move_down p_bottom) : reference_bounds.move_past_bottom @@ -598,7 +598,7 @@ module Asciidoctor # def flow_bounding_box left = 0, opts = {} original_y = y - # QUESTION should preserving original_x be an option? + # QUESTION: should preserving original_x be an option? original_x = bounds.absolute_left - margin_box.absolute_left canvas do bounding_box [margin_box.absolute_left + original_x + left, margin_box.absolute_top], opts do @@ -808,19 +808,19 @@ module Asciidoctor state.compress = false if state.compress # can't use compression if using template prev_text_rendering_mode = (defined? @text_rendering_mode) ? @text_rendering_mode : nil delete_page if opts[:replace] - # NOTE use functionality provided by prawn-templates + # NOTE: use functionality provided by prawn-templates start_new_page_discretely template: file, template_page: opts[:page] # prawn-templates sets text_rendering_mode to :unknown, which breaks running content; revert @text_rendering_mode = prev_text_rendering_mode if page.imported_page? yield if block_given? - # NOTE set page size & layout explicitly in case imported page differs + # NOTE: set page size & layout explicitly in case imported page differs # I'm not sure it's right to start a new page here, but unfortunately there's no other # way atm to prevent the size & layout of the imported page from affecting subsequent pages advance_page size: prev_page_size, layout: prev_page_layout if opts.fetch :advance, true elsif opts.fetch :advance, true delete_page - # NOTE see previous comment + # NOTE: see previous comment advance_page size: prev_page_size, layout: prev_page_layout else delete_page @@ -838,7 +838,7 @@ module Asciidoctor else image file, (options.merge position: :center, vposition: :center, fit: [bounds.width, bounds.height]) end - # NOTE advance to newly created page just in case the image function threw off the cursor + # NOTE: advance to newly created page just in case the image function threw off the cursor go_to_page image_page_number nil end @@ -907,13 +907,13 @@ module Asciidoctor def scratch? (@_label ||= (state.store.info.data[:Scratch] ? :scratch : :primary)) == :scratch rescue - false # NOTE this method may get called before the state is initialized + false # NOTE: this method may get called before the state is initialized end alias is_scratch? scratch? def dry_run &block scratch = get_scratch_document - # QUESTION should we use scratch.advance_page instead? + # QUESTION: should we use scratch.advance_page instead? scratch.start_new_page start_page_number = scratch.page_number start_y = scratch.y @@ -927,7 +927,7 @@ module Asciidoctor scratch.instance_exec(&block) end scratch.font_scale = prev_font_scale - # NOTE don't count excess if cursor exceeds writable area (due to padding) + # NOTE: don't count excess if cursor exceeds writable area (due to padding) full_page_height = scratch.effective_page_height partial_page_height = [full_page_height, start_y - scratch.y].min scratch_bounds.instance_variable_set :@x, original_x @@ -942,7 +942,7 @@ module Asciidoctor def keep_together &block available_space = cursor total_height, = dry_run(&block) - # NOTE technically, if we're at the page top, we don't even need to do the + # NOTE: technically, if we're at the page top, we don't even need to do the # dry run, except several uses of this method rely on the calculated height if total_height > available_space && !at_page_top? && total_height <= effective_page_height advance_page diff --git a/lib/asciidoctor/pdf/ext/prawn/images.rb b/lib/asciidoctor/pdf/ext/prawn/images.rb index 30a8a137..d7b87419 100644 --- a/lib/asciidoctor/pdf/ext/prawn/images.rb +++ b/lib/asciidoctor/pdf/ext/prawn/images.rb @@ -45,7 +45,7 @@ module Asciidoctor img_size = img_obj.document.sizing { width: img_size.output_width, height: img_size.output_height } else - # NOTE build_image_object caches image data previously loaded + # NOTE: build_image_object caches image data previously loaded _, img_size = ::File.open(path, 'rb') {|fd| build_image_object fd } { width: img_size.width, height: img_size.height } end diff --git a/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb b/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb index 160c44ea..8b27d596 100644 --- a/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb +++ b/lib/asciidoctor/pdf/ext/rouge/formatters/prawn.rb @@ -65,7 +65,7 @@ module Rouge line_numbers ? (fragments << (create_linenum_fragment linenum)) : (start_of_line = true) fragments << @highlight_line_fragment.dup if highlight_lines && highlight_lines[linenum] elsif val.include? LF - # NOTE we assume if the fragment ends in a line feed, the intention was to match a line-oriented form + # NOTE: we assume if the fragment ends in a line feed, the intention was to match a line-oriented form line_oriented = val.end_with? LF base_fragment = create_fragment tok, val val.each_line do |line| @@ -75,7 +75,7 @@ module Rouge end fragments << (line_oriented ? (base_fragment.merge text: line, inline_block: true) : (base_fragment.merge text: line)) next unless line.end_with? LF - # NOTE eagerly append linenum fragment or line highlight if there's a next line + # NOTE: eagerly append linenum fragment or line highlight if there's a next line linenum += 1 line_numbers ? (fragments << (create_linenum_fragment linenum)) : (start_of_line = true) fragments << @highlight_line_fragment.dup if highlight_lines && highlight_lines[linenum] @@ -88,10 +88,10 @@ module Rouge fragments << (create_fragment tok, val) end end - # NOTE pad numbers that have less digits than the largest line number - # FIXME we could store these fragments so we don't have find them again + # NOTE: pad numbers that have less digits than the largest line number + # FIXME: we could store these fragments so we don't have find them again if line_numbers && (linenum_w = linenum.to_s.length) > 1 - # NOTE extra column is the trailing space after the line number + # NOTE: extra column is the trailing space after the line number linenum_w += 1 fragments.each do |fragment| fragment[:text] = (fragment[:text].rjust linenum_w, NoBreakSpace).to_s if fragment[:linenum] @@ -108,10 +108,10 @@ module Rouge else val[0] = GuardedIndent if start_of_line && (val.start_with? ' ') val.gsub! InnerIndent, GuardedInnerIndent if val.include? InnerIndent - # QUESTION do we need the call to create_fragment if val contains only spaces? consider bg + # QUESTION: do we need the call to create_fragment if val contains only spaces? consider bg #fragment = create_fragment tok, val fragment = val.rstrip.empty? ? { text: val } : (create_fragment tok, val) - # NOTE we assume if the fragment ends in a line feed, the intention was to match a line-oriented form + # NOTE: we assume if the fragment ends in a line feed, the intention was to match a line-oriented form fragment[:inline_block] = true if (start_of_line = val.end_with? LF) fragment end diff --git a/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb b/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb index 9fc913b9..0c449a5f 100644 --- a/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb +++ b/lib/asciidoctor/pdf/formatted_text/inline_image_arranger.rb @@ -43,7 +43,7 @@ module Asciidoctor::PDF::FormattedText drop = scratch image_path = fragment[:image_path] - # NOTE only attempt to convert an unresolved (i.e., String) value + # NOTE: only attempt to convert an unresolved (i.e., String) value if ::String === (image_w = fragment[:image_width]) image_w = [available_w, (image_w.end_with? '%') ? (image_w.to_f / 100 * available_w) : image_w.to_f].min end @@ -60,9 +60,9 @@ module Asciidoctor::PDF::FormattedText enable_file_requests_with_root: (::File.dirname image_path), cache_images: doc.cache_uri svg_size = image_w ? svg_obj.document.sizing : - # NOTE convert intrinsic dimensions to points; constrain to content width + # NOTE: convert intrinsic dimensions to points; constrain to content width (svg_obj.resize width: [svg_obj.document.sizing.output_width, available_w].min) - # NOTE the best we can do is make the image fit within full height of bounds + # NOTE: the best we can do is make the image fit within full height of bounds if (image_h = svg_size.output_height) > max_image_h image_w = (svg_obj.resize height: (image_h = max_image_h)).output_width else @@ -71,7 +71,7 @@ module Asciidoctor::PDF::FormattedText fragment[:image_obj] = svg_obj else # TODO: cache image info based on path (Prawn caches based on SHA1 of content) - # NOTE image_obj is constrained to image_width by renderer + # NOTE: image_obj is constrained to image_width by renderer image_obj, image_info = ::File.open(image_path, 'rb') {|fd| doc.build_image_object fd } if image_w if image_w == image_info.width @@ -79,20 +79,20 @@ module Asciidoctor::PDF::FormattedText else image_h = image_w * (image_info.height.fdiv image_info.width) end - # NOTE convert intrinsic dimensions to points; constrain to content width + # NOTE: convert intrinsic dimensions to points; constrain to content width elsif (image_w = to_pt image_info.width, :px) > available_w image_h = (image_w = available_w) * (image_info.height.fdiv image_info.width) else image_h = to_pt image_info.height, :px end - # NOTE the best we can do is make the image fit within full height of bounds + # NOTE: the best we can do is make the image fit within full height of bounds image_w = (image_h = max_image_h) * (image_info.width.fdiv image_info.height) if image_h > max_image_h fragment[:image_obj] = image_obj fragment[:image_info] = image_info end doc.fragment_font fragment do - # NOTE if image height exceeds line height by more than 1.5x, increase the line height + # NOTE: if image height exceeds line height by more than 1.5x, increase the line height # FIXME: we could really use a nicer API from Prawn here; this is an ugly hack if (f_height = image_h) > (line_font = doc.font).height * 1.5 # align with descender (equivalent to vertical-align: bottom in CSS) @@ -106,7 +106,7 @@ module Asciidoctor::PDF::FormattedText end end - # NOTE we can't rely on the fragment width because the line wrap mechanism ignores it; + # NOTE: we can't rely on the fragment width because the line wrap mechanism ignores it; # it only considers the text (string) and character spacing, rebuilding the string several times fragment[:text] = PlaceholderChar fragment[:actual_character_spacing] = doc.character_spacing @@ -117,11 +117,11 @@ module Asciidoctor::PDF::FormattedText logger.warn %(could not embed image: #{image_path}; #{$!.message}#{::Prawn::Errors::UnsupportedImageType === $! && !(defined? ::GMagick::Image) ? '; install prawn-gmagick gem to add support' : ''}) unless scratch drop = true # delegate to cleanup logic in ensure block ensure - # NOTE skip rendering image in scratch document or if image can't be loaded + # NOTE: skip rendering image in scratch document or if image can't be loaded if drop fragment.delete :callback fragment.delete :image_info - # NOTE retain key to indicate we've visited fragment already + # NOTE: retain key to indicate we've visited fragment already fragment[:image_obj] = nil end end diff --git a/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb b/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb index 729dfcf7..1fc5f6d3 100644 --- a/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb +++ b/lib/asciidoctor/pdf/formatted_text/inline_image_renderer.rb @@ -31,8 +31,8 @@ module Asciidoctor::PDF::FormattedText case data[:image_format] when 'svg' (image_obj = data[:image_obj]).options[:at] = [image_left, image_top] - # NOTE prawn-svg messes with the cursor; use float to workaround - # NOTE prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80) + # NOTE: prawn-svg messes with the cursor; use float to workaround + # NOTE: prawn-svg 0.24.0, 0.25.0, & 0.25.1 didn't restore font after call to draw (see mogest/prawn-svg#80) pdf.float do pdf.character_spacing(data[:actual_character_spacing]) { image_obj.draw } image_obj.document.warnings.each do |img_warning| diff --git a/lib/asciidoctor/pdf/formatted_text/parser.rb b/lib/asciidoctor/pdf/formatted_text/parser.rb index 6c2fb509..a901a9a6 100644 --- a/lib/asciidoctor/pdf/formatted_text/parser.rb +++ b/lib/asciidoctor/pdf/formatted_text/parser.rb @@ -99,7 +99,7 @@ module Markup end module Element1 - # NOTE content only applies to non-void elements (second part of rule) + # NOTE: content only applies to non-void elements (second part of rule) def content { type: :element, name: (tag_element = elements[0]).name.to_sym, attributes: tag_element.attributes, pcdata: elements[1].content } end diff --git a/lib/asciidoctor/pdf/formatted_text/parser.treetop b/lib/asciidoctor/pdf/formatted_text/parser.treetop index 29b4a1bb..6e28cdc1 100644 --- a/lib/asciidoctor/pdf/formatted_text/parser.treetop +++ b/lib/asciidoctor/pdf/formatted_text/parser.treetop @@ -20,7 +20,7 @@ grammar Markup # void_element / start_tag complex end_tag &{|seq| seq[0].name == seq[2].name } { void_element / start_tag complex end_tag { - # NOTE content only applies to non-void elements (second part of rule) + # NOTE: content only applies to non-void elements (second part of rule) def content { type: :element, name: (tag_element = elements[0]).name.to_sym, attributes: tag_element.attributes, pcdata: elements[1].content } end @@ -48,8 +48,8 @@ grammar Markup end rule tag_name - # QUESTION faster to do regex? - # QUESTION what about supporting hr? + # QUESTION: faster to do regex? + # QUESTION: what about supporting hr? 'a' / 'strong' / 'em' / 'code' / 'color' / 'font' / 'span' / 'button' / 'key' / 'sup' / 'sub' / 'mark' / 'del' end diff --git a/lib/asciidoctor/pdf/formatted_text/transform.rb b/lib/asciidoctor/pdf/formatted_text/transform.rb index 9599052b..e34ce9cc 100644 --- a/lib/asciidoctor/pdf/formatted_text/transform.rb +++ b/lib/asciidoctor/pdf/formatted_text/transform.rb @@ -135,15 +135,15 @@ module Asciidoctor def apply parsed, fragments = [], inherited = nil previous_fragment_is_text = false - # NOTE we use each since using inject is slower than a manual loop + # NOTE: we use each since using inject is slower than a manual loop parsed.each do |node| case node[:type] when :element # case 1: non-void element if node.key? :pcdata - # NOTE skip element if it has no children + # NOTE: skip element if it has no children if (pcdata = node[:pcdata]).empty? - ## NOTE handle an empty anchor element (i.e., <a ...></a>) + ## NOTE: handle an empty anchor element (i.e., <a ...></a>) #if (tag_name = node[:name]) == :a # seed = clone_fragment inherited, text: DummyText # fragments << build_fragment(seed, tag_name, node[:attributes]) @@ -153,7 +153,7 @@ module Asciidoctor tag_name = node[:name] attributes = node[:attributes] parent = clone_fragment inherited - # NOTE decorate child fragments with inherited properties from this element + # NOTE: decorate child fragments with inherited properties from this element apply pcdata, fragments, (build_fragment parent, tag_name, attributes) previous_fragment_is_text = false end @@ -244,7 +244,7 @@ module Asciidoctor else fragment[:color] = rgb end - # QUESTION should we even support r,g,b and c,m,y,k as individual values? + # QUESTION: should we even support r,g,b and c,m,y,k as individual values? elsif (r_val = attrs[:r]) && (g_val = attrs[:g]) && (b_val = attrs[:b]) fragment[:color] = [r_val, g_val, b_val].map {|e| '%02X' % e.to_i }.join elsif (c_val = attrs[:c]) && (m_val = attrs[:m]) && (y_val = attrs[:y]) && (k_val = attrs[:k]) @@ -262,7 +262,7 @@ module Asciidoctor fragment[:size] = value end end - # NOTE width is used for font-based icons + # NOTE: width is used for font-based icons if (value = attrs[:width]) fragment[:width] = value fragment[:align] = :center @@ -275,7 +275,7 @@ module Asciidoctor visible = true # a element can have no attributes, so short-circuit if that's the case unless attrs.empty? - # NOTE href, anchor, and name are mutually exclusive; nesting is not supported + # NOTE: href, anchor, and name are mutually exclusive; nesting is not supported if (value = attrs[:anchor]) fragment[:anchor] = value elsif (value = attrs[:href]) @@ -283,7 +283,7 @@ module Asciidoctor $1 ? CharEntityTable[$1.to_sym] : [$2 ? $2.to_i : ($3.to_i 16)].pack('U1') end) : value elsif (value = attrs[:id] || attrs[:name]) - # NOTE text is null character, which is used as placeholder text so Prawn doesn't drop fragment + # NOTE: text is null character, which is used as placeholder text so Prawn doesn't drop fragment fragment = { name: value, callback: [InlineDestinationMarker] } if (type = attrs[:type]) fragment[:type] = type.to_sym @@ -299,7 +299,7 @@ module Asciidoctor when :del styles << :strikethrough when :span - # NOTE spaces in style value are superfluous for our purpose; split drops record after trailing ; + # NOTE: spaces in style value are superfluous for our purpose; split drops record after trailing ; attrs[:style].tr(' ', '').split(';').each do |style| pname, pvalue = style.split ':', 2 # TODO: text-transform @@ -312,7 +312,7 @@ module Asciidoctor when 7 fragment[:color] = pvalue.slice 1, 6 if pvalue.start_with? '#' end - # QUESTION should we support the 3 character form? + # QUESTION: should we support the 3 character form? #when 3 # fragment[:color] = pvalue.each_char.map {|c| c * 2 }.join #when 4 @@ -325,7 +325,7 @@ module Asciidoctor fragment[:align] = pvalue.to_sym fragment[:callback] = (fragment[:callback] || []) | [InlineTextAligner] when 'width' - # NOTE implicitly activates inline-block behavior + # NOTE: implicitly activates inline-block behavior fragment[:width] = pvalue when 'background-color' # background-color needed to support syntax highlighters if (pvalue.start_with? '#') && (HexColorRx.match? pvalue) diff --git a/lib/asciidoctor/pdf/pdfmark.rb b/lib/asciidoctor/pdf/pdfmark.rb index dfd5f456..d94a272a 100644 --- a/lib/asciidoctor/pdf/pdfmark.rb +++ b/lib/asciidoctor/pdf/pdfmark.rb @@ -32,7 +32,7 @@ module Asciidoctor end def generate_file pdf_file - # QUESTION should we use the extension pdfmeta to be more clear? + # QUESTION: should we use the extension pdfmeta to be more clear? ::File.write %(#{pdf_file}mark), generate end end diff --git a/lib/asciidoctor/pdf/sanitizer.rb b/lib/asciidoctor/pdf/sanitizer.rb index ddae962b..1879a3c3 100644 --- a/lib/asciidoctor/pdf/sanitizer.rb +++ b/lib/asciidoctor/pdf/sanitizer.rb @@ -26,8 +26,8 @@ module Asciidoctor # Strip leading, trailing and repeating whitespace, remove XML tags and # resolve all entities in the specified string. # - # FIXME move to a module so we can mix it in elsewhere - # FIXME add option to control escaping entities, or a filter mechanism in general + # FIXME: move to a module so we can mix it in elsewhere + # FIXME: add option to control escaping entities, or a filter mechanism in general def sanitize string string = string.gsub SanitizeXMLRx, '' if string.include? '<' string = string.gsub(CharRefRx) { $1 ? BuiltInNamedEntities[$1] : ([$2 ? $2.to_i : ($3.to_i 16)].pack 'U1') } if string.include? '&' diff --git a/lib/asciidoctor/pdf/theme_loader.rb b/lib/asciidoctor/pdf/theme_loader.rb index 84b0bd54..bd871f11 100644 --- a/lib/asciidoctor/pdf/theme_loader.rb +++ b/lib/asciidoctor/pdf/theme_loader.rb @@ -39,7 +39,7 @@ module Asciidoctor end def self.resolve_theme_file theme_name = nil, theme_dir = nil - # NOTE if .yml extension is given, assume it's a path (don't append -theme.yml) + # NOTE: if .yml extension is given, assume it's a path (don't append -theme.yml) if theme_name && (theme_name.end_with? '.yml') # FIXME: restrict to jail! if theme_dir @@ -59,7 +59,7 @@ module Asciidoctor ::File.absolute_path asset_path, (theme_dir || ThemesDir) end - # NOTE base theme is loaded "as is" (no post-processing) + # NOTE: base theme is loaded "as is" (no post-processing) def self.load_base_theme (::OpenStruct.new ::SafeYAML.load_file BaseThemePath).tap {|theme| theme.__dir__ = ThemesDir } end @@ -153,7 +153,7 @@ module Asciidoctor process_entry %(#{key}_#{key == 'role' || !(subkey.include? '-') ? subkey : (subkey.tr '-', '_')}), subval, data end elsif key.end_with? '_color' - # QUESTION do we really need to evaluate_math in this case? + # QUESTION: do we really need to evaluate_math in this case? data[key] = to_color evaluate val, data elsif key.end_with? '_content' data[key] = (expand_vars val.to_s, data).to_s @@ -174,7 +174,7 @@ module Asciidoctor end end - # NOTE we assume expr is a String + # NOTE: we assume expr is a String def expand_vars expr, vars if (idx = (expr.index '$')) if idx == 0 && expr =~ LoneVariableRx @@ -208,8 +208,8 @@ module Asciidoctor def evaluate_math expr return expr if !(::String === expr) || ColorValue === expr # resolve measurement values (e.g., 0.5in => 36) - # QUESTION should we round the value? perhaps leave that to the precision functions - # NOTE leave % as a string; handled by converter for now + # QUESTION: should we round the value? perhaps leave that to the precision functions + # NOTE: leave % as a string; handled by converter for now original, expr = expr, (resolve_measurement_values expr) loop do if (expr.count '*/') > 0 diff --git a/spec/admonition_spec.rb b/spec/admonition_spec.rb index a33c699f..74467edd 100644 --- a/spec/admonition_spec.rb +++ b/spec/admonition_spec.rb @@ -469,7 +469,7 @@ describe 'Asciidoctor::PDF::Converter - Admonition' do (expect to_file).to visually_match 'admonition-custom-raster-icon.pdf' end - # NOTE this is a pretty flimsy feature and probably needs some rethink + # NOTE: this is a pretty flimsy feature and probably needs some rethink it 'should allow theme to control width of admonition icon image using admonition_label_min_width key' do pdf_theme = { admonition_label_min_width: 40 } pdf = to_pdf <<~'EOS', pdf_theme: pdf_theme, attribute_overrides: { 'docdir' => fixtures_dir }, analyze: :image diff --git a/spec/font_spec.rb b/spec/font_spec.rb index 34f9269b..61817952 100644 --- a/spec/font_spec.rb +++ b/spec/font_spec.rb @@ -293,7 +293,7 @@ describe 'Asciidoctor::PDF::Converter - Font' do (expect lines[1]).to eql %(foo\u2011bar\u2011foo) end - # NOTE this test demonstrates a bug in Prawn + # NOTE: this test demonstrates a bug in Prawn it 'should break line if no-break hyphen is isolated into its own fragment' do pdf = to_pdf <<~'EOS', analyze: true foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar **foo**‑**bar**‑**foo** diff --git a/spec/formatted_text_formatter_spec.rb b/spec/formatted_text_formatter_spec.rb index 16f4e1a8..ed8ed7c3 100644 --- a/spec/formatted_text_formatter_spec.rb +++ b/spec/formatted_text_formatter_spec.rb @@ -89,7 +89,7 @@ describe Asciidoctor::PDF::FormattedText::Formatter do end end - # QUESTION should these go in a separate file? + # QUESTION: should these go in a separate file? context 'integration' do it 'should format constrained strong phrase' do pdf = to_pdf '*strong*', analyze: true diff --git a/spec/image_spec.rb b/spec/image_spec.rb index 51307d3e..2bd34252 100644 --- a/spec/image_spec.rb +++ b/spec/image_spec.rb @@ -739,7 +739,7 @@ describe 'Asciidoctor::PDF::Converter - Image' do (expect pages[0][:size]).to eql PDF::Core::PageGeometry::SIZES['A4'] (expect pages[0][:text][-1][:string]).to eql '1' (expect pages[1][:size].map(&:to_f)).to eql PDF::Core::PageGeometry::SIZES['LETTER'] - # NOTE no running content on imported pages + # NOTE: no running content on imported pages (expect pages[1][:text]).to be_empty (expect pages[2][:text][-1][:string]).to eql '3' end @@ -764,7 +764,7 @@ describe 'Asciidoctor::PDF::Converter - Image' do (expect pages[0][:size]).to eql PDF::Core::PageGeometry::SIZES['A4'] (expect pages[0][:text][-1][:string]).to eql '1' (expect pages[1][:size].map(&:to_f)).to eql PDF::Core::PageGeometry::SIZES['LETTER'] - # NOTE no running content on imported pages + # NOTE: no running content on imported pages (expect pages[1][:text]).to be_empty (expect pages[2][:text][-1][:string]).to eql '3' end @@ -1151,7 +1151,7 @@ describe 'Asciidoctor::PDF::Converter - Image' do end).to log_message severity: :WARN, message: '~image to embed not found or not readable' end unless windows? - # NOTE this test also verifies space is allocated for an inline image at the start of a line + # NOTE: this test also verifies space is allocated for an inline image at the start of a line it 'should convert multiple images on the same line', visual: true do to_file = to_pdf_file <<~'EOS', 'image-multiple-inline.pdf' image:logo.png[Asciidoctor,12] is developed on image:tux.png[Linux,12]. @@ -1429,7 +1429,7 @@ describe 'Asciidoctor::PDF::Converter - Image' do end context 'Border' do - # NOTE tests center alignment + # NOTE: tests center alignment it 'should draw border around PNG image if border width and border color are set in the theme', visual: true do pdf_theme = { image_border_width: 0.5, @@ -1475,7 +1475,7 @@ describe 'Asciidoctor::PDF::Converter - Image' do (expect to_file).to visually_match 'image-border-fit-page.pdf' end - # NOTE tests right alignment + # NOTE: tests right alignment it 'should draw border around SVG if border width and border color are set in the theme', visual: true do pdf_theme = { image_border_width: 1, diff --git a/spec/list_spec.rb b/spec/list_spec.rb index 9e678a89..4a738246 100644 --- a/spec/list_spec.rb +++ b/spec/list_spec.rb @@ -756,7 +756,7 @@ describe 'Asciidoctor::PDF::Converter - List' do (expect pdf.lines).to eql ['• l1', '1. l2', '▪ l3', 'a. l4', '▪ l5', 'i. l6', '• l1'] end - # NOTE expand this test as necessary to cover the various permutations + # NOTE: expand this test as necessary to cover the various permutations it 'should not insert excess space between nested lists or list items with block content', visual: true do to_file = to_pdf_file <<~'EOS', 'list-complex-nested.pdf' * list item @@ -1365,7 +1365,7 @@ describe 'Asciidoctor::PDF::Converter - List' do colist_num_top_y = colist_num_text[:y] + colist_num_text[:font_size] gap = bottom_line_y - colist_num_top_y - # NOTE default outline list spacing is 6 + # NOTE: default outline list spacing is 6 (expect gap).to be > 6 (expect gap).to be < 8 end diff --git a/spec/page_spec.rb b/spec/page_spec.rb index bb929946..66cb04ed 100644 --- a/spec/page_spec.rb +++ b/spec/page_spec.rb @@ -29,7 +29,7 @@ describe 'Asciidoctor::PDF::Converter - Page' do content EOS (expect pdf.pages).to have_size 1 - # NOTE pdf-core 0.8 coerces whole number floats to integers + # NOTE: pdf-core 0.8 coerces whole number floats to integers (expect pdf.pages[0][:size].map(&:to_f)).to eql PDF::Core::PageGeometry::SIZES['LETTER'] end @@ -364,7 +364,7 @@ describe 'Asciidoctor::PDF::Converter - Page' do = Book Title :media: prepress :doctype: book - // NOTE setting front-cover-image to ~ informs converter cover page will be added later + // NOTE: setting front-cover-image to ~ informs converter cover page will be added later :front-cover-image: ~ == First Chapter diff --git a/spec/running_content_spec.rb b/spec/running_content_spec.rb index fe114812..3cc7829f 100644 --- a/spec/running_content_spec.rb +++ b/spec/running_content_spec.rb @@ -934,7 +934,7 @@ describe 'Asciidoctor::PDF::Converter - Running Content' do footer_recto_right_content: 'text right', } - # NOTE the exact y position is affected by the font height and line metrics, so use a fuzzy check + # NOTE: the exact y position is affected by the font height and line metrics, so use a fuzzy check { 'top' => 72, 'middle' => 42, 'bottom' => 12, ['top', 10] => 62, ['bottom', -10] => 22 }.each do |valign, expected_y| pdf = to_pdf 'body', pdf_theme: (pdf_theme.merge footer_vertical_align: valign), enable_footer: true, analyze: true left_text = (pdf.find_text 'text left')[0] diff --git a/spec/section_spec.rb b/spec/section_spec.rb index f0465b6b..c1ed78a2 100644 --- a/spec/section_spec.rb +++ b/spec/section_spec.rb @@ -394,7 +394,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do end it 'should add chapter signifier to chapter title if section numbering is enabled and chapter-signifier attribute is set' do - # NOTE chapter-label is the legacy name + # NOTE: chapter-label is the legacy name { 'chapter-label' => 'Ch', 'chapter-signifier' => 'Ch' }.each do |attr_name, attr_val| pdf = to_pdf <<~EOS, analyze: true = Book Title @@ -413,7 +413,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do end it 'should add chapter signifier to chapter title if section numbering and toc are enabled and chapter-signifier attribute is set' do - # NOTE chapter-label is the legacy name + # NOTE: chapter-label is the legacy name { 'chapter-label' => 'Ch', 'chapter-signifier' => 'Ch' }.each do |attr_name, attr_val| pdf = to_pdf <<~EOS, analyze: true = Book Title @@ -433,7 +433,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do end it 'should not add chapter label to chapter title if section numbering is enabled and chapter-signifier attribute is empty' do - # NOTE chapter-label is the legacy name + # NOTE: chapter-label is the legacy name %w(chapter-label chapter-signifier).each do |attr_name| pdf = to_pdf <<~EOS, analyze: true = Book Title @@ -495,7 +495,7 @@ describe 'Asciidoctor::PDF::Converter - Section' do (expect text[1][:font_size]).to be 13 end - # QUESTION is this the right behavior? should the value default to Preface instead? + # QUESTION: is this the right behavior? should the value default to Preface instead? it 'should not promote anonymous preface in book doctype to preface section if preface-title attribute is empty' do input = <<~'EOS' = Book Title diff --git a/spec/source_spec.rb b/spec/source_spec.rb index 20f862a6..94151e55 100644 --- a/spec/source_spec.rb +++ b/spec/source_spec.rb @@ -70,7 +70,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do echo_text = (pdf.find_text 'echo')[0] (expect echo_text).not_to be_nil - # NOTE the echo keyword should be highlighted + # NOTE: the echo keyword should be highlighted (expect echo_text[:font_color]).to eql '008800' end @@ -85,7 +85,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do EOS echo_text = (pdf.find_text 'echo')[0] - # NOTE the echo keyword should not be highlighted + # NOTE: the echo keyword should not be highlighted (expect echo_text).to be_nil end @@ -128,7 +128,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do if (Gem::Version.new Rouge.version) >= (Gem::Version.new '2.1.0') echo_text = pdf.find_unique_text 'echo' (expect echo_text).not_to be_nil - # NOTE the echo keyword should be highlighted + # NOTE: the echo keyword should be highlighted (expect echo_text[:font_color]).to eql '008800' end end @@ -144,7 +144,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do EOS echo_text = pdf.find_unique_text 'echo' - # NOTE the echo keyword should not be highlighted + # NOTE: the echo keyword should not be highlighted (expect echo_text).to be_nil end @@ -681,7 +681,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do echo_text = (pdf.find_text 'echo')[0] (expect echo_text).not_to be_nil - # NOTE the echo keyword should be highlighted + # NOTE: the echo keyword should be highlighted (expect echo_text[:font_color]).to eql '008800' end @@ -696,7 +696,7 @@ describe 'Asciidoctor::PDF::Converter - Source' do EOS echo_text = (pdf.find_text 'echo')[0] - # NOTE the echo keyword should not be highlighted + # NOTE: the echo keyword should not be highlighted (expect echo_text).to be_nil end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index ad7a2fe8..b0d45d56 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -19,7 +19,7 @@ require 'pathname' unless defined? Pathname require 'pdf/inspector' require 'socket' -# NOTE fix invalid bits for PNG in Gmagick +# NOTE: fix invalid bits for PNG in Gmagick Gmagick.prepend (Module.new do def initialize image_blob super @@ -27,7 +27,7 @@ Gmagick.prepend (Module.new do end end) if defined? ::GMagick::Image -# NOTE fix warning in Prawn::Font:TTF +# NOTE: fix warning in Prawn::Font:TTF Prawn::Font::TTF.prepend (Module.new do def initialize *args @italic_angle = nil @@ -35,7 +35,7 @@ Prawn::Font::TTF.prepend (Module.new do end end) -# NOTE fix warning in TTFunk::Table +# NOTE: fix warning in TTFunk::Table TTFunk::Table.prepend (Module.new do def initialize *args @offset = nil @@ -163,7 +163,7 @@ class EnhancedPDFTextInspector < PDF::Inspector end def show_text text, kerned = false - # NOTE this may be a rough approximation + # NOTE: this may be a rough approximation text_width = (@state.current_font.unpack text).reduce 0 do |width, code| width + (@state.current_font.glyph_width code) * @font_settings[:size] / 1000.0 end @@ -284,7 +284,7 @@ class LineInspector < PDF::Inspector @style = :solid end else - # NOTE we can only guess because we don't know the width of the line + # NOTE: we can only guess because we don't know the width of the line @style = :dashed end end @@ -690,7 +690,7 @@ end RSpec::Matchers.define :visually_match do |reference_filename| reference_path = (Pathname.new reference_filename).absolute? ? reference_filename : (File.join __dir__, 'reference', reference_filename) match do |actual_path| - # NOTE uncomment this line and run `bundle exec rspec -t ~visual` to detect which tests use a visual match + # NOTE: uncomment this line and run `bundle exec rspec -t ~visual` to detect which tests use a visual match #warn caller.find {|it| it.include? '_spec.rb:' } return false unless File.exist? reference_path images_output_dir = output_file 'visual-comparison-workdir' diff --git a/spec/table_spec.rb b/spec/table_spec.rb index 2377b435..d3af2276 100644 --- a/spec/table_spec.rb +++ b/spec/table_spec.rb @@ -326,7 +326,7 @@ describe 'Asciidoctor::PDF::Converter - Table' do |=== EOS - # NOTE it appears Prawn table is drawing the same grid line multiple times + # NOTE: it appears Prawn table is drawing the same grid line multiple times lines = pdf.lines.uniq (expect lines).to have_size 4 lines.each do |line| @@ -564,7 +564,7 @@ describe 'Asciidoctor::PDF::Converter - Table' do (expect col2_width).to be > col1_width pdf = to_pdf input, analyze: true - # NOTE second column should not wrap + # NOTE: second column should not wrap (expect pdf.lines).to eql ['short a much wider table column'] end @@ -737,7 +737,7 @@ describe 'Asciidoctor::PDF::Converter - Table' do reference_pdf = to_pdf input, analyze: :line pdf = to_pdf input, pdf_theme: { table_cell_padding: [10, 3, 10, 3] }, analyze: :line - # NOTE the line under the head row should moved down + # NOTE: the line under the head row should moved down (expect pdf.lines[0][:from][:y]).to be < reference_pdf.lines[0][:from][:y] end @@ -758,7 +758,7 @@ describe 'Asciidoctor::PDF::Converter - Table' do reference_a1_text = (reference_pdf.find_text 'A1')[0] a1_text = (pdf.find_text 'A1')[0] - # NOTE the first body row should be moved down + # NOTE: the first body row should be moved down (expect a1_text[:y]).to be < reference_a1_text[:y] end @@ -1853,7 +1853,7 @@ describe 'Asciidoctor::PDF::Converter - Table' do (expect a3_text[:page_number]).to be 2 first_list_item_text = (pdf.find_text 'list item', page_number: 2)[0] last_list_item_text = (pdf.find_text 'list item', page_number: 3)[-1] - # NOTE if this is off, the margin box got mangled + # NOTE: if this is off, the margin box got mangled (expect last_list_item_text[:x]).to eql first_list_item_text[:x] end diff --git a/spec/theme_loader_spec.rb b/spec/theme_loader_spec.rb index e979c058..da06be95 100644 --- a/spec/theme_loader_spec.rb +++ b/spec/theme_loader_spec.rb @@ -303,7 +303,7 @@ describe Asciidoctor::PDF::ThemeLoader do it 'should not inherit from base theme when loading default theme' do theme = subject.load_theme - # NOTE table_border_style is only set in the base theme + # NOTE: table_border_style is only set in the base theme (expect theme.table_border_style).to be_nil end @@ -494,7 +494,7 @@ describe Asciidoctor::PDF::ThemeLoader do (expect theme.page_background_color).to be_a subject::HexColorValue (expect theme.base_font_color).to eql '000000' (expect theme.base_font_color).to be_a subject::HexColorValue - # NOTE this assertion tests that the value can be an integer, not a string + # NOTE: this assertion tests that the value can be an integer, not a string (expect theme.heading_font_color).to eql '333333' (expect theme.heading_font_color).to be_a subject::HexColorValue (expect theme.link_font_color).to eql '428BCA' @@ -554,7 +554,7 @@ describe Asciidoctor::PDF::ThemeLoader do (expect theme.menu_caret_content).not_to be_a subject::HexColorValue end - # NOTE this only works when the theme is read from a file + # NOTE: this only works when the theme is read from a file it 'should allow hex color values to be prefixed with # for any key' do theme = subject.load_theme 'hex-color-shorthand', fixtures_dir (expect theme.base_font_color).to eql '222222' @@ -566,7 +566,7 @@ describe Asciidoctor::PDF::ThemeLoader do (expect theme.footer_background_color).to be_nil end - # NOTE this is only relevant when the theme is read from a file + # NOTE: this is only relevant when the theme is read from a file it 'should not coerce color-like values to string if key does not end with color' do theme = subject.load_theme 'color-like-value', fixtures_dir (expect theme.footer_height).to be 100 diff --git a/spec/toc_spec.rb b/spec/toc_spec.rb index 2d27bac4..be9e4ace 100644 --- a/spec/toc_spec.rb +++ b/spec/toc_spec.rb @@ -793,7 +793,7 @@ describe 'Asciidoctor::PDF::Converter - TOC' do (expect doctitle_text[:y]).to be > toc_title_text[:y] (expect toc_title_text[:y]).to be > content_top_text[:y] (expect toc_bottom_text[:y]).to be > content_top_text[:y] - # NOTE assert there's no excess gap between end of toc and start of content + # NOTE: assert there's no excess gap between end of toc and start of content (expect toc_bottom_text[:y] - content_top_text[:y]).to be < 35 end @@ -837,7 +837,7 @@ describe 'Asciidoctor::PDF::Converter - TOC' do idx_content_top = idx if candidate[:string] == 'Section 1' && candidate[:font_size] == 22 end (expect text[idx_toc_bottom][:y]).to be > text[idx_content_top][:y] - # NOTE assert there's no excess gap between end of toc and start of content + # NOTE: assert there's no excess gap between end of toc and start of content (expect text[idx_toc_bottom][:y] - text[idx_content_top][:y]).to be < 50 end |