Useful package map-paragraphs

<TeXmacs|2.1.2>

<style|source>

<\body>
  <\active*>
    <\src-title>
      <src-style-file|email|1.0>

      <\src-purpose>
        In-context paragraph decoration
      </src-purpose>

      <\src-copyright|2024>
        Sam Liddicott
      </src-copyright>

      <\src-license>
        This software falls under the <hlink|GNU general public license,
        version 3 or later|$TEXMACS_PATH/LICENSE>. It comes WITHOUT ANY
        WARRANTY WHATSOEVER. You should have received a copy of the license
        which the software. If not, see <hlink|http://www.gnu.org/licenses/gpl-3.0.html|http://www.gnu.org/licenses/gpl-3.0.html>.
      </src-license>
    </src-title>
  </active*>

  <\active*>
    <\src-comment>
      map-args can be used to enumerate the paragraphs of a document tag
      passed as an argument, but only for a macro invoked directly from the
      macro. Nested macro invocations tend to wrap the document tag in
      further document tags, making it hard to get at the paragraph elements

      This package provides \<less\>map-paragraphs-with\|foo\|x\<gtr\> where
      foo is the macro to be invoked on each paragraph, and x is a document
      block usually originating in the document.
    </src-comment>
  </active*>

  <use-package|generic>\ 

  <\active*>
    <\src-comment>
      These are internal macros which recurse the document tree of the
      argument to decorate paragraphs within the document context (unlike
      datoms).

      Example to enclose paragraphs in \P...\Q:

      <\inactive*>
        <\map-paragraphs-with|<macro|x|\P<arg|x>\Q>>
          one

          two

          three
        </map-paragraphs-with>
      </inactive*>

      Whereas you might use map-args to make that work as a macro invoked
      from the top level document, this wouldn't:

      <\inactive*>
        <assign|auto-quote|<macro|x|<map-paragraphs-with|<macro|x|\P<arg|x>\Q>|<arg|x>>>>

        <\auto-quote>
          one

          two

          three
        </auto-quote>
      </inactive*>

      because the argument propagated from auto-quote would have an extra
      document tag enclosing it, and so map-args would only detect one
      argument which would be the whole set of paragraphs.
    </src-comment>
  </active*>

  <\active*>
    <\src-comment>
      macro map-paragraphs-default- can be overridden using
      \<less\>with\|map-paragraphs-default-\|new-definition\|...\<gtr\> to
      replace rendering of non-document tags, but it is easier to use
      \<less\>map-paragraphs-with\|new-definition\|...\<gtr\>
    </src-comment>
  </active*>

  <assign|map-paragraphs-default-|<macro|x|<arg|x>>>

  <assign|map-paragraphs-document|<\macro|x>
    <quasi|<map-paragraphs*|<unquote*|<arg|x>>>>
  </macro>>

  <assign|map-paragraphs*|<xmacro|x|<map-args|map-paragraphs|document|x>>>

  <\active*>
    <\src-comment>
      These are public macros but you almost always want to use
      \<less\>map-paragraphs-with\|new-definition\|...\<gtr\>
    </src-comment>
  </active*>

  <assign|map-paragraphs|<\macro|x>
    <compound|<if|<provides|<merge|map-paragraphs-|<get-label|<arg|x>>>>|<merge|map-paragraphs-|<get-label|<arg|x>>>|map-paragraphs-default->|<arg|x>>
  </macro>>

  <assign|map-paragraphs-with|<\macro|foo|x>
    <with|map-paragraphs-default-|<arg|foo>|<map-paragraphs|<arg|x>>>
  </macro>>

  <\active*>
    <\src-comment>
      The mechanism is simple. Get the label of the top-level tag of the
      argument and look for a handler defined as
      map-paragraphs-\<less\>label\<gtr\> and invoke that, otherwise invoke
      map-paragraphs-default-

      The only tag I currently know that I am interested in recursing is the
      document tag because outer document tags keep getting inserted
      everytime a document value is passed as a parameter.

      So each time we find a document tag, we call map-paragraphs* for all
      it's children which are obtained using quasi and unquote* (usually used
      for xmacros).
    </src-comment>
  </active*>

  \;
</body>

<\initial>
  <\collection>
    <associate|preamble|true>
  </collection>
</initial>