Support figureGraphics(...) outside figure

Fix some comments

doxia-core/src/test/java/org/apache/maven/doxia/sink/impl/AbstractSinkTest.java

@@ -650,12 +650,9 @@ public void testTable() {
     }
 
     /**
-     * Checks that the sequence <code>[table(),
-     * tableRows(Sink.JUSTIFY_CENTER, false), tableRow(), tableCell(),
-     * text(cell), tableCell_(), tableRow_(), tableRows_(), tableCaption(),
-     * text(caption), tableCaption_(), table_()]</code>,
+     * Checks that the sequence of table with header methods
      * invoked on the current sink, produces the same result as
-     * {@link #getTableBlock getTableBlock}(cell, caption).
+     * {@link #getTableWithHeaderBlock(String...)}.
      */
     @Test
     public void testTableWithHeader() {
@@ -665,7 +662,7 @@ public void testTableWithHeader() {
         try (IntStream cellStream = getCellStreamForNewRow(3)) {
             cellStream.forEach(col -> {
                 sink.tableHeaderCell();
-                sink.text("header" + col);
+                sink.text("header_" + col);
                 sink.tableHeaderCell_();
             });
         }
@@ -690,7 +687,7 @@ public void testTableWithHeader() {
         sink.close();
 
         String actual = testWriter.toString();
-        String expected = getTableWithHeaderBlock("header", "row1_", "row2_");
+        String expected = getTableWithHeaderBlock("header_", "row1_", "row2_");
 
         if (isXmlSink()) {
             assertThat(wrapXml(actual), isIdenticalTo(wrapXml(expected)));
@@ -1338,6 +1335,12 @@ protected String getOutputDir() {
      */
     protected abstract String getTableBlock(String cell, String caption);
 
+    /**
+     * Returns a Table with header block on the current sink.
+     * @param rowPrefixes the text prefix used in the individual rows.
+     * @return the result of invoking a Table with header block on the current sink.
+     * @see #testTableWithHeader()
+     */
     protected abstract String getTableWithHeaderBlock(String... rowPrefixes);
 
     /**

doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownSink.java

@@ -48,7 +48,7 @@ public class MarkdownSink extends AbstractTextSink implements MarkdownMarkup {
     // Instance fields
     // ----------------------------------------------------------------------
 
-    /**  A buffer that holds the current text when headerFlag or bufferFlag set to <code>true</code>. This value of this buffer is already escaped. */
+    /**  A buffer that holds the current text when headerFlag or bufferFlag set to <code>true</code>. This content of this buffer is already escaped. */
     private StringBuffer buffer;
 
     /**  author. */
@@ -69,21 +69,24 @@ public class MarkdownSink extends AbstractTextSink implements MarkdownMarkup {
     /**  tableCaptionFlag. */
     private boolean tableCaptionFlag;
 
-    /** tableCellFlag, set to true inside table (header) cells */
+    /** tableCellFlag, set to {@code true} inside table (header) cells */
     private boolean tableCellFlag;
 
-    /** tableRowHeaderFlag, set to true for table rows containing at least one table header cell  */
+    /** tableRowHeaderFlag, set to {@code true} for table rows containing at least one table header cell  */
     private boolean tableHeaderCellFlag;
 
     /**  headerFlag. */
     private boolean headerFlag;
 
-    /**  bufferFlag, set to true in certain elements to prevent direct writing during {@link #text(String, SinkEventAttributes)} */
+    /**  bufferFlag, set to {@code true} in certain elements to prevent direct writing during {@link #text(String, SinkEventAttributes)} */
     private boolean bufferFlag;
 
     /**  verbatimFlag. */
     private boolean verbatimFlag;
 
+    /** figure flag, set to {@code true} between {@link #figure(SinkEventAttributes)} and {@link #figure_()} events */
+    private boolean figureFlag;
+
     /**  number of cells in a table. */
     private int cellCount;
 
@@ -160,9 +163,11 @@ protected void init() {
         this.startFlag = true;
         this.tableCaptionFlag = false;
         this.tableCellFlag = false;
+        this.tableHeaderCellFlag = false;
         this.headerFlag = false;
         this.bufferFlag = false;
         this.verbatimFlag = false;
+        this.figureFlag = false;
         this.cellCount = 0;
         this.cellJustif = null;
         this.listStyles.clear();
@@ -556,6 +561,7 @@ public void tableCaption_() {
     @Override
     public void figure(SinkEventAttributes attributes) {
         figureSrc = null;
+        figureFlag = true;
     }
 
     @Override
@@ -568,16 +574,28 @@ public void figureCaption_() {
         bufferFlag = false;
     }
 
-    /** {@inheritDoc} */
+    @Override
     public void figureGraphics(String name, SinkEventAttributes attributes) {
-        figureSrc = name;
+        figureSrc = escapeMarkdown(name);
+        if (!figureFlag) {
+            Object alt = attributes.getAttribute(SinkEventAttributes.ALT);
+            if (alt == null) {
+                alt = "";
+            }
+            writeImage(escapeMarkdown(alt.toString()), name);
+        }
     }
 
     @Override
     public void figure_() {
+        writeImage(buffer.toString(), figureSrc);
+        figureFlag = false;
+    }
+
+    private void writeImage(String alt, String src) {
         write("![");
-        write(buffer.toString());
-        write("](" + figureSrc + ")");
+        write(alt);
+        write("](" + src + ")");
     }
 
     /** {@inheritDoc} */
@@ -716,8 +734,7 @@ public void text(String text, SinkEventAttributes attributes) {
             inline(attributes);
         }
         if (tableCaptionFlag) {
-            // TODO: emitting via HTML markup caption requires buffering the whole table as <caption> must be the first
-            // child of <table>
+            // table caption cannot even be emitted via XHTML in markdown as there is no suitable location
             LOGGER.warn("Ignoring unsupported table caption in Markdown");
         } else if (headerFlag || bufferFlag) {
             buffer.append(escapeMarkdown(text));

doxia-modules/doxia-module-markdown/src/test/java/org/apache/maven/doxia/module/markdown/MarkdownSinkTest.java

@@ -168,7 +168,7 @@ protected String getDefinitionListBlock(String definum, String definition) {
 
     /** {@inheritDoc} */
     protected String getFigureBlock(String source, String caption) {
-        return "![" + (caption != null ? getEscapedText(caption) : "") + "](" + source + ")";
+        return "![" + (caption != null ? getEscapedText(caption) : "") + "](" + getEscapedText(source) + ")";
     }
 
     /** {@inheritDoc} */
@@ -182,8 +182,8 @@ protected String getTableBlock(String cell, String caption) {
     @Override
     protected String getTableWithHeaderBlock(String... rowPrefixes) {
         StringBuilder expectedMarkup = new StringBuilder();
-        expectedMarkup.append(MarkdownMarkup.TABLE_ROW_PREFIX + rowPrefixes[0] + "0|" + rowPrefixes[0] + "1|"
-                + rowPrefixes[0] + "2|" + EOL);
+        expectedMarkup.append(MarkdownMarkup.TABLE_ROW_PREFIX + getEscapedText(rowPrefixes[0]) + "0|"
+                + getEscapedText(rowPrefixes[0]) + "1|" + getEscapedText(rowPrefixes[0]) + "2|" + EOL);
         expectedMarkup.append(MarkdownMarkup.TABLE_ROW_PREFIX + "---|---:|:---:|" + EOL);
         for (int n = 1; n < rowPrefixes.length; n++) {
             expectedMarkup.append(MarkdownMarkup.TABLE_ROW_PREFIX + getEscapedText(rowPrefixes[n]) + "0|"

doxia-modules/doxia-module-markdown/src/test/resources/test.md

@@ -16,3 +16,5 @@ code
 |---|:---:|---:|
 |b `code` az|test|test|
 |b **bold** im|test|test|
+
+![Some figure](figure.jpg)