New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support full/extended markdown syntax #66

Closed
tomaz opened this Issue Feb 13, 2011 · 2 comments

Comments

Projects
None yet
1 participant
@tomaz
Owner

tomaz commented Feb 13, 2011

Included documents would benefit from using full Markdown syntax. Extended syntax is also welcome. Although it would be possible to implement this directly within appledoc source, it's probably better to use third party library such as discount.

In any case it would be preferrable to use the same solution for both, code comments and included documents parsing. There are couple of issues with using third party libraries (all depend on actual library used!):

  • They tend to be geared towards creating full html documents while only fractions are needed for appledoc purposes. This could be solvable by updating library source or postprocessing.
  • Another consequence of being geared towards full html solution is using many different options that affect the outcome. Although these could be added as command line switches to appledoc it would add a lot of overhead. Sensible defaults would solve this for most cases, but it might require interface for tweaking various options.
  • Cross references to source code and included documents must not require []() syntax. This could be solvable by doing preprocessing and converting cross refs to []() style and then passing resulting string as source to library.
  • Markdown uses single star and underscore for <em> and double for <strong> while appledoc uses single star for strong and single underscore for em. Seems more intuitive to me this way... Preprocessing might be used for fixing this.
  • @ directives parsing: this could also be handled by preprocessing.

See also #41 and #7.

@tomaz

This comment has been minimized.

Owner

tomaz commented Feb 13, 2011

Been researching a bit. Discount produces just marked portion of html (without html, head and body tags), so any source can be directly translated into output. With a bit of preprocessing, mainly to detect cross references this should be doable.

I've found some issues that may require more than just a simple conversion: for example this: GBAppledocApplication would be converted into [GBAppledocApplication](http://...) before passing it to discount, however if the whole thing is escaped inside tick marks `` which is quite common, the whole part is converted to code instead of being recognized as a href. No big deal, just something I'll need to pay attention to... :)

There will probably be more issues like this and I guess some things may work slightly differently too. But the gain would still be bigger than losses...

@tomaz

This comment has been minimized.

Owner

tomaz commented Feb 24, 2011

Updated version to 2.0.3, build 632. Closed by ced35dc. Closed by ced35dc.

This took quite a bit longer than estimated, but was worth it as now full Markdown syntax is supported (with extensions). Instead of doing internal parsing of source code, I embedded Discount for this. Check the documentation to see all options it supports!

Documentation is now 100% Markdown compatible, although several appledoc features are preserved and change default Markdown syntax:

  • Single star is converted to strong tag instead of em as in Markdown. You can also use Markdown default double star or double underscore for the same effect!
  • Single star and underscore markers are still converted to strong/em combination. Markdown would otherwise convert these to strong only.
  • Cross references are handled the same way as before.
  • You can now use cross references to documented objects with arbitrary descriptions (#41) using Markdown inline links like this: [description](Class) or `[description]([Class method:] "title"). If the address is recognized as documented object, this will be converted to proper link using description as the text! This works for classes, categories, protocols, methods and static documents!
  • You can also use the same for Markdown ref links, so this: [description][1] followed by: [1]: Class or [1]: [Class method:] &quot;title&quot; is properly converted to link to object, method or static document.

Generally the documentation should be backwards compatible, so most users won't notice a difference, but there are a couple of points that are handled differently now with Discount, so some may experience different layout in the generated HTML files. You should now follow Markdown syntax. Perhaps most noticeable: example blocks following list item are now treated as continuation of list item, whereas before they were converted to example blocks. Hopefully these changes are for the best and definitely more in-spec with Markdown... If you experience some strange behavior, open a new issue or comment on this one...

IMPORTANT: Don't forget to update template files!

NOTE: Actually this commit only updates version, the actual solution was implemented on a temporary branch, merged to development at b7b92f8. The actual implementation starts at 1ad2f9d and ends with 226b767. GitHub still doesn't support linking commits to issues beyond closing... Not too elegant, but this was far too large to be handled by a single commit!

tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012

Updated version to 2.0.3, build 632. Closes tomaz#41. Closes tomaz#66.
This took quite a bit longer than estimated, but was worth it as now full Markdown syntax is supported (with extensions). Instead of doing internal parsing of source code, I embedded [Discount](http://www.pell.portland.or.us/~orc/Code/discount/) for this. Check the documentation to see all options it supports!

Documentation is now 100% Markdown compatible, although several appledoc features are preserved and change default Markdown syntax:

- Single star is converted to strong tag instead of em as in Markdown. You can also use Markdown default double star or double underscore for the same effect!
- Single star and underscore markers are still converted to strong/em combination. Markdown would otherwise convert these to strong only.
- Cross references are handled the same way as before.
- You can now use cross references to documented objects with arbitrary descriptions (tomaz#41) using Markdown inline links like this: `[description](Class)` or `[description]([Class method:] "title"). If the address is recognized as documented object, this will be converted to proper link using description as the text! This works for classes, categories, protocols, methods and static documents!
- You can also use the same for Markdown ref links, so this: `[description][1]` followed by: `[1]: Class` or `[1]: [Class method:] "title"` is properly converted to link to object, method or static document.

Generally the documentation should be backwards compatible, so most users won't notice a difference, but there are a couple of points that are handled differently now with Discount, so some may experience different layout in the generated HTML files. You should now follow [Markdown syntax](http://daringfireball.net/projects/markdown/syntax). Perhaps most noticeable: example blocks following list item are now treated as continuation of list item, whereas before they were converted to example blocks. Hopefully these changes are for the best and definitely more in-spec with Markdown... If you experience some strange behavior, open a new issue or comment on this one...

*IMPORTANT:* Don't forget to update template files!

*NOTE:* Actually this commit only updates version, the actual solution was implemented on a temporary branch, merged to development at b7b92f8. The actual implementation starts at 1ad2f9d and ends with 226b767. GitHub still doesn't support linking commits to issues beyond closing... Not too elegant, but this was far too large to be handled by a single commit!

This issue was closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment