Paragraph numbering

Hi,

Main question:
I'm looking for an easy way to number paragraphs with asciidoctor / asciidoctor-pdf.

Full story:
first of all congrats to this great project! I'm really impressed with what asciidoctor (and especially asciidoctor-pdf) is capable of doing!

I am working as a volunteer together with the United Nations and the Emergency Telecoms Cluster (http://www.etcluster.org/). We are providing internet access to the humanitarian community in disaster areas.

The system we're using needs to be documented well because in an emergency you don't want to lose time because of poor documentation.

I am looking to switch to asciidoctor for these documentation purposes.

One requirement we have for easy referencing individual instructions within the manual is to have each paragraph numbered.

Is there an easy way to achieve this with asciidoctor?

Thanks!
Alex

Hi

Im quite new to AsciiDoctor but I think this is what you want



To have the processor auto-number the sections, define the numbered attribute in the document header:

:numbered:
You can also use this attribute entry above any section title in the document to toggle the auto-numbering setting. When you want to turn off the numbering, add an exclamation point to the end of the attribute name:

:numbered!:

== Unnumbered Section

I found it on http://asciidoctor.org/docs/asciidoc-writers-guide/#titles-titles-titles

Hi Adrian,

thanks a lot for your answer!

Unfortunately, the :numbered: keyword is not quite what I'm after. In addition to having numbered chapters and section headings, I am looking for a way to number each paragraph within a section.

Cheers,
Alex

Ah I see, yeah now I read it again, its clear. Hope you find a solution

Alex,

Thanks for the kind words about Asciidoctor and Asciidoctor PDF. I certainly hope that you'll be able to make use of it for your virtuous cause!

Numbering paragraphs is easily achieved using a Treeprocessor extension. A Treeprocessor runs after the blocks in the document have been parsed into an internal structure. At that point, you can modify the content to add automatic numbering of paragraphs.

There are two ways to achieve this. You can either insert text at the start of the paragraph or you can give the paragraph a title. Either way will enable you to inject numbering into the content dynamically.

Here's a quick implementation to show you the idea.

[source,ruby]

----

require 'asciidoctor'

require 'asciidoctor/extensions'

class NumberParagraphsTreeprocessor < Asciidoctor::Extensions::Treeprocessor

  def process document

    document.find_by(context: :paragraph).each_with_index do |p, idx|

      pnum = idx + 1

      # number paragraph using title

      p.title = %(#{pnum}.)

      # or insert number into paragraph

      p.lines.first.prepend %(#{pnum}. )

    end

  end

end

Extensions.register do

  treeprocessor NumberParagraphsTreeprocessor

end

----

Keep in mind that the Treeprocessor can alter the document regardless of what output format you are producing.

I recommend that you use a Treeprocessor approach for this use case as opposed to modifying the source document as this metadata should not concern the author (at least that's my understanding).

This might be a nice addition to https://github.com/asciidoctor/asciidoctor-extensions-lab where we can bake the idea more fully.

-Dan

On Wed, Aug 19, 2015 at 3:34 PM, alexf [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

Main question:
I'm looking for an easy way to number paragraphs with asciidoctor / asciidoctor-pdf.

Full story:
first of all congrats to this great project! I'm really impressed with what asciidoctor (and especially asciidoctor-pdf) is capable of doing!

I am working as a volunteer together with the United Nations and the Emergency Telecoms Cluster (http://www.etcluster.org/). We are providing internet access to the humanitarian community in disaster areas.

The system we're using needs to be documented well because in an emergency you don't want to lose time because of poor documentation.

I am looking to switch to asciidoctor for these documentation purposes.

One requirement we have for easy referencing individual instructions within the manual is to have each paragraph numbered.

Is there an easy way to achieve this with asciidoctor?

Thanks!
Alex

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Paragraph-numbering-tp3697.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Paragraph-numbering-tp3697p3890.html

To unsubscribe from Paragraph numbering, click here.
NAML

I solved this myself by adding `{counter:¶}` to the start of each paragraph in my document. The ¶ symbol is easily typed on OSX using Option-7. Anyway, it's a bit of boilerplate, but it has nearly the desired effect without having to include custom code.