Objects within HTML tables not getting linked.

[jkleinwaechter]

I have a case in a companion guide where a referenced object is inside of a table and the rendered html shows up as what appears to be markdown text for a link. In other words not converted to an anchor tag. When I use the same object outside of the table, it works as expected.

I am using direct html for the tables rather than markdown, as I needed some more control. So I put the object in a markdown table and see if that changed things. That displayed the link properly. So it is just the link inside the html that causes the issue.

I suspect this has something to do with the order in which the processing of markdown and object references happen??

Any insight would be helpful as I really need the table control. If I could find a way to control the markdown tables better that would work as well.

---

Source

test of link out in the open - creates link as expected

WorldpayAPI swiperWithDelegate()

test of link inside markdown table - creates link as expected

|Header1|Header2|
|-------|-------|
| WorldpayAPI | swiperWithDelegate() |

Original code - only yields markdown.

<table>
<thead>
    <tr>
      <th bgcolor="#CC0000" colspan="2"><FONT COLOR="linen">Card Information Capture Methods</FONT>
      </th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Address the Attached Device
        </td>
        <td>Gets a reference to the attached device and allows you to set up handlers for device events.
            <br/><br/>
            See:  WorldpayAPI swiperWithDelegate()
        </td>
    </tr>

Result

[tomaz]

Hmm, it makes sense given how appledoc and Markdown processing works:

1. appledoc first preprocesses sources and converts all known cross references into Markdown syntax
2. Preprocessed sources are then passed to generator which converts then from Markdown to HTML

So appledoc finds known cross reference inside HTML and converts it to Markdown syntax, but Markdown -> HTML generator ignores HTML blocks entirely and simply renders them without any processing, leaving the Markdown link syntax (from appledoc) intact...

There are several ways this could be resolved (in no particular order, as they come to mind):

1. appledoc uses discount for Markdown processing, there might be a flag that tells it to handle Markdown inside HTML. In this case a new command line flag would need to be added to appledoc that would in turn trigger the flag for discount.
2. appledoc preprocessor would need to be altered to have it ignore HTML.

Both above require code changes, 1 is relatively simple if discount allows it, 2 is more complex. But there's also a way to do it without any code change, though it requires you to manually handle cross references: use --explicit-crossref option which will require you to embed all cross references you want to treat as cross references within less than and greater than signs (<Name> for example). In this case you'd use <WorldpayAPI> everywhere you want it to convert to cross reference but simply WorldpayAPI in your HTML code to prevent it being matched as cross reference. Note, this puts you into full control of what gets to be treated as crossref and what not, but takes away automatic cross referencing of course. If you don't like default format, you can optionally combine it with --crossref-format to tailor it to your liking.

[jkleinwaechter]

Makes sense - thank you!