Development

This page should be used for documentation in support of Issue discussions.

Docx Output

As per Issue #29, docx's native capabilities should be used for equations, captions and numbering. Pandoc-eqnos should take an approach similar to what it does for LaTeX and html output.

Note: I (@tomduck) am not a Word user. I'm going to need good advice from users to come up with a solution to this problem.

Output from Pandoc

Consider a very simple document, represented in markdown as follows:

$$ y = f(x) $${#eq:1}

Ref to +@eq:1.

I processed this document with pandoc 2.1 and the pandoc-eqnos filter, producing a docx file. The OOXML can be viewed by unziping the docx file (into a new directory, otherwise it will spam your current one) and opening word/document.xml. Here is the result, formatted for easy viewing:

<?xml version="1.0" encoding="UTF-8"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w10="urn:schemas-microsoft-com:office:word" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing">
  <w:body>

    <w:p>
      <w:pPr><w:pStyle w:val="FirstParagraph" /></w:pPr>
      <w:bookmarkStart w:id="0" w:name="eq:1" /><w:r><w:t /></w:r>
    </w:p>

    <w:p>
      <w:pPr><w:pStyle w:val="BodyText" /></w:pPr>
      <m:oMathPara>
        <m:oMathParaPr><m:jc m:val="center" /></m:oMathParaPr>
        <m:oMath>
          <m:r><m:t>y</m:t></m:r>
          <m:r><m:t>=</m:t></m:r>
          <m:r><m:t>f</m:t></m:r>
          <m:r><m:t>(</m:t></m:r>
          <m:r><m:t>x</m:t></m:r>
          <m:r><m:t>)</m:t></m:r>
          <m:r><m:t>  </m:t></m:r>
          <m:r><m:t>(</m:t></m:r>
          <m:r><m:t>1</m:t></m:r>
          <m:r><m:t>)</m:t></m:r>
        </m:oMath>
      </m:oMathPara>
    </w:p>

    <w:p>
      <w:pPr><w:pStyle w:val="FirstParagraph" /></w:pPr>
      <w:bookmarkEnd w:id="0" />
    </w:p>

    <w:p>
      <w:pPr><w:pStyle w:val="BodyText" /></w:pPr>
      <w:r><w:t xml:space="preserve">Ref to eq.</w:t></w:r>
      <w:r><w:t xml:space="preserve"> </w:t></w:r>
      <w:hyperlink w:anchor="eq:1">
        <w:r>
          <w:rPr><w:rStyle w:val="Hyperlink" /></w:rPr>
          <w:t xml:space="preserve">1</w:t>
        </w:r>
      </w:hyperlink>
      <w:r><w:t xml:space="preserve">.</w:t></w:r>
    </w:p>

    <w:sectPr />

  </w:body>
</w:document>

There are four paragraph elements, encapsulated in <w:p>...</w:p> tags. They are:

1. The bookmark start;
2. The equation;
3. The bookmark end; and
4. The "Ref to eq. 1." text and link.

Questions

The following questions need to be answered; discuss in Issue #34, please.

1. Is the bookmarking done correctly? (Note to self: Why aren't the bookmark start and end encapsulated in a single paragraph? What I have coded in pandoc_eqnos.py seems to come out differently.)

2. Is the equation ooxml in paragraph 2 correct? Should the equation be encapsulated in another element? What is best? I will likely need to override pandoc's implementation in any case.

3. How should the equation number be attached to the equation? At present the number is hard-coded. Docx's native capabilities should be used instead (i.e., something equivalent to LaTeX's \label macro).

4. How should the reference number be written into paragraph 4? At present the number is hard-coded. Docx's native capabilities should be used instead (i.e., something equivalent to LaTeX's \ref macro).

To do

The answers to the above questions can presumably be obtained by creating a Word document and unpacking the document.xml file. The Word document should be as close as possible to the markdown document I give above. Please note the Word version.