Documentation Question

Monkey Archive Forums/Digital Discussion/Documentation Question

impixi(Posted 2014) [#1]
Hello all,

I'm writing some documentation in HTML that incorporates programming code examples. I'd be interested to know what the preferred behaviour is for such situations:

1. Fully expanded code embedded within the HTML document?

2. A click-able link that loads the code into a separate tab, preserving the parent window?

3. A click-able link that loads the code into the same frame as it was clicked?

4. A click-able "Example" heading that expands/collapses the code directly within the HTML document?

5. A click-able "Example" heading that displays a "modal" code-viewing pop-up "window"?

The code files are presently stored as separate, plain text files and therefore are not "decorated". This makes it easier to change them without having to modify the main HTML document. It also takes advantage of most browsers' default behaviour of displaying text in a monospace font.

Currently I have implemented option 4 (expandable/collapseable "example" headings) using JavaScript to provide the behaviour. There's still a quirk with it, regarding adjusting an iframe's height relating to its contents. However, I'm starting to think I'm wasting my time with this approach.

I'm tending towards option 3, which would also be the easiest to implement and maintain. I like it because I can just click on the example, issue "select-all" and "copy" commands with my keyboard, and then hit the bowser's "back" button. But maybe it's just me who likes this approach?

Comments?


ziggy(Posted 2014) [#2]
I would go for fully expanded code as long as the sample code is short. It's better to use short code to explain speciffic concepts when possible. That said, whenever a more extensive example is required, then I would go for the collapsable/expandable approach you seem to already have.
you can add a copy to clipboard button into the page, that automatically selects the text and puts it on the clipbard by using JavaScript. Not sure how this could be done exactly, but I think it should not be too difficult as long as the browser allows text to be copied to the clipboard


impixi(Posted 2014) [#3]
Thanks for your input, ziggy. I've basically settled on the approach you suggest. Though I'm unsure If I'll stick with it. I'm still trying some other things too. I posted the same question on the BlitzBasic General forum where I explain things a little more.

Regarding copying text to the clipboard using Javascript: You can't do it universally without silly hacks due to potential security violations. God, it's such a pain coding for browsers...


Danilo(Posted 2014) [#4]
I think the same as ziggy. Small examples inline, bigger examples within a a scrollbox or hide/show button.
Additionally, I think syntax highlighting is important, as it makes the sources more readable.

Some syntax highlighters:
- Highlight
- GeSHi
- highlight.js
- SyntaxHighlighter
- Prism


impixi(Posted 2014) [#5]
Thanks Danilo. I'll incorporate highlighting if I can find a suitable, lightweight solution. I'll check each of those links. The only highlighting API I've looked into so far is:

https://code.google.com/p/google-code-prettify/

In case anyone is wondering, I'm working on a "Monkey Module Reference". At the moment it's at the "proof of concept" stage, meaning I've compiled and written additional content for a single module (monkey.lang and associated classes), seeing if I can construct a decent format and getting a feel for how much effort is involved.


impixi(Posted 2014) [#6]
Wow. Integrating highlight.js was almost too easy. It already has Monkey as a supported language. Seems to work well...