Since LiveCode went open source we’ve been able to accept community contributions to LiveCode itself, but one area we haven’t had available properly is documentation.

Documentation is one place where we know that community contributions would be really valuable, and where people who don’t want to get into the workings of the engine can still share their expertise.

We have a long list of improvements we want to make to our docs, and one of the things near the top of this list is our guides.

Currently we have 6 guides available from the Developers page  plus the User Guide available within the LiveCode product, under the Help Menu. We are planning to update the Documentation portal in the product in preparation for Widgets, allowing us to display all our guides and API documentation, as well as any Widget documentation, in a single place.

The plan is to write all our guides in Markdown, a plain text formatting system designed so it can be converted to HTML for display. This will also allow us to add the guides to GitHub, which allows display and editing of Markdown files written in GitHub Flavored Markdown. 

Happily the guides for Beginners, Developers, Mobile, Desktop Externals, iOS Externals and LiveCode Server were initially written in Markdown, so only some small tweaks were needed to make them GitHub flavored. The User Guide however was another matter.

Note: throughout this blog I’ll be using StackEdit, an in-browser markdown editor to show my Markdown source and the rendered HTML.

What did I need to do

The first step in preparing the User Guide to be brought up to date was to convert it from a Word document to Markdown.

To do this I chose to use Pandoc, a universal document converter which can convert from Word to Markdown, as well as a variety of other document formats.

Pandoc has a lot of options, allowing you to specify how you want the ouput formatted. In this case I want 

ATX style headers

Markdown offers 2 styles of headers, Setext and ATX.

-Setext headers underline <h1> headers with equal signs and <h2> headers with hyphens.

– ATX headers put 1-6 hash marks at the start of a header. The number of hash marks corresponds to the header level.

 

Pipe tables, this means any tables in the Mardown will be formatted as below

| First Header  | Second Header |

| —————- | ——————-|

| Content Cell  |    Content Cell   |

| Content Cell  |    Content Cell   |

 

  Extract media

  This option extracts images and other media to a folder, and includes the image references in the document.

pandoc -f docx -t markdown_github+pipe_tables --atx-headers --extract-media=images -o UserGuide.md UserGuide.docx

The result

 

This looked good and I was pretty happy with the result. There were headings of different levels, italicised text, links and bullet points. All in all pretty good for 1 line in the command line.

But wait, something was missing. In the User Guide the System Requirements section is marked as a note and highlighted in a box. This additional formatting hadn’t been included in the Markdown file. As I scrolled though the Markdown document I noticed a few cases of lost formatting which would need a little extra work to include in the Markdown.

The reason that this additional styling did not persist after the conversion is that there were custom styles in the Word document that did not convert. Having looked into it I couldn’t find a simple way to include these in the Markdown conversion but if any Blog readers know of a way please do leave me a comment.

Tips, Notes, Important and Caution warnings

The first thing I noticed was that Tips, Notes, Important and Caution warning were no longer highlighted as described and used in the User Guide.

I wanted to ensure these sections would be highlighted in the Markdown version using  Blockquotes, denoted in Markdown using >

so 

> **Note:** This is  a note.

Displays As

But first I had to find all the Tips, Notes and Warnings in the original document. Each type was highlighted in a different color, could I use that to find pull out the relevant text? Yes, by converting the Word document to HTML I could find all the text contained in colored boxes and pull it out.

I then created a very simple stack to find the Tips. Tips are included in a yellow box, in the HTML source this looks like

<P LANG="en-US" STYLE="margin-right: 0.42cm; margin-bottom: 0.42cm; background: #fefec2; line-height: 0.39cm">This style of text box tells you about an alternative way to do something or describes a shortcut.</P>

So all I needed to do was to find all the occurences of this style of paragraph, pull out the text and that gave me all the tips. Then I repeated this for Notes, Important and Caution, just changing the code to look for the relevant background color.

I created my stack, added a field and imported the HTML source into it, then added a button that would output the tips it found to the message box.

The matchChunk function returns the position of a given substring in a string, so by searching for the <p> and </p> tags that describe the Tip style of paragraph I could extract all the tips.

I then used the lineOffset function to find the line numbers of these lines in the Markdown file and prepended them with > **Tip:**

I then repeated this process for the Notes, Important and Caution sections, just checking for the correct background color in each case.

Tables

The next thing I noticed was that tables weren’t displaying quite correctly.

The reason for this was that Markdown requires tables to have headers, whereas the tables in my Markdown documents were formatted like this, with no headers.

|————————————————————–|——————————|

| **Windows, Linux and Unix keyboard shortcuts** | **Mac OS equivalent** |

| Control                                                                                       | Command                            |

| Alt                                                                                                | Option                                   |

| Right-click                                                                                 | Control-click (or right-click if you have a two button mouse) |

 

My first thought was to take the line after the separator and move it above, like this

| **Windows, Linux and Unix keyboard shortcuts** | **Mac OS equivalent** |

|————————————————————–|——————————|

| Control                                                                                       | Command                            |

| Alt                                                                                                | Option                                   |

| Right-click                                                                                 | Control-click (or right-click if you have a two button mouse) |

This would have worked in this example as the first line happens to be the headers but there are many instances where the table doesn’t actually have headers, so this would not work.

Instead I decided to add empty titles to each table. Again this was simple to do in LiveCode. In this case because I wanted to step through each line in the Markdown file and rebuild it with extra lines in some cases I created a new Markdown file from the original.

This method could probably be optimised but as it should (hopefully) only be run a very small number of times I did not take the time to optimise it.

The resulting Markdown

|&nbsp;                                                                                         |&nbsp;                                   |                                

|————————————————————–|——————————|

| **Windows, Linux and Unix keyboard shortcuts** | **Mac OS equivalent** |

| Control                                                                                       | Command                            |

| Alt                                                                                                | Option                                   |

| Right-click                                                                                 | Control-click (or right-click if you have a two button mouse) |

 

The resulting display

Code Sections

The final challenge was to find all the code sections. I had hoped to use the HTML source as I did for the Tip sections but while the Tips and Notes were unique enough to use lineOffset to find them in the Markdown this wouldn’t work for phrases like “mouseUp” or “answer”.

Instead I set the htmlText of a field and then used the property to find all the pieces of code and their associated full lines. I do this by finding any text  that appears in the courier font.

This gives me a list of line numbers and the text that should be put into code blocks. GitHub markdown has two styles of code highlighting, in-line and code blocks. Inline code has backticks around it e.g.

When the mouse is released a `mouseUp` message is sent.

Blocks of code and fenced by 3 back ticks e.g.

` ` `

on mouseUp

doSomething

end mouseUp

` ` `

 

Once I have this list I can step through each code block, decide whether it is inline or a code block and update the markdown based on this.

This can result in multiple code blocks together, one after another e.g.

` ` ` on mouseUp` ` `

` ` `doSomething` ` `

` ` `end mouseUp` ` `

These should be combined into a single code block, one way to do this is by replacing (“` ` `” & return & “` ` `”) with return, using 

replace (“` ` `” & return & “` ` `”) with return tMarkdown

so the markdown above would become

` ` `on mouseUp

doSomething

end mouseUp` ` `

The final step is to ensure there is a new line before and after code blocks to ensure correct display. This can be done using

 replace “` ` `” with (return & “` ` `” & return) in tMarkdown

so the Markdown above becomes

` ` `

on mouseUp

doSomething

end mouseUp

` ` `

 

After completing all these steps code blocks display as below

 

 

 

Final steps

After all these steps the Markdown version of the User Guide was pretty complete. There was a little manual work to do, just passing over the document and making sure everything looked ok but it saved a lot of work and got the User Guide into a good state for updates and contributions.

Coming soon

We still have some work so do polishing and updating the User Guide and other guides, and we need to decide on the best way to get them into GitHub ready for contributions but we’ll be keeping you posted as work progresses.

read more

On Tuesday 17th June we were invited to take part in a BBC initiative called Connected Studio.  This is a BBC initiative for collaborative innovation with some of the best of the UK’s online creatives.  Over the last few years they have run a set of events on a variety of topics including Weather & Travel, The Commonwealth Games and The Natural History Unit, each aiming to develop innovative ideas for digital media output with the resources, experience and power of the BBC behind them.

The event we were invited to take part in was Coding for Teenagers, a day long brainstorming and briefing event taking place across three sites in Salford, Cardiff and Glasgow. The challenge was to “Inspire your people to realise their creative potential through technology”. The UK is currently facing a severe skills shortage in the technology sector and the goal of the day was to come up with ways to encourage and inspire 13-16 year olds to get more involved with technology, in a creative way rather than just as end users, the brief was 

“to create an appealing digital experience with a coding component for teenagers aged 13-16.”

Needless to say we were excited to be invited to take part in such a  fun event with such an important goal, and so in line with the ideas and message behind LiveCode. So on one of the warmest, sunniest mornings of the year Kevin, Ben, Neil and I headed across to Glasgow ready sit inside watching presentations in the dark and coming up with some ideas.

The day started off with an introduction and live link up between the three sites. This was followed by an ideas board and team forming, and some presentations on the research that has been done in this area to help inspire us and point us in the right direction when coming up with ideas.

A lot of the issues that inspired this event are of interest to me. As a female developer I’m in the minority and I think that its important to help teenagers, and in particular girls, realise how varied and creative the work can be. 

The briefing document we were provided with specifically mentioned some of these points.

The Audience

Your challenge is to make sure we inspire not just teenagers in general, but teenage girls aged 13-16 in particular. That’s because only 

18% of computing professionals are women (E-Skills, 2012) and the number of female computer science graduates is down 13% (HESA, 

2013). A study for Nesta (TNS, 2014) suggests girls are less likely to make things using digital technology. They are also twice as unlikely to 

learn about it outside of school. 

Ideally, we’re looking for ideas that appeal to both boys and girls, however, we’re particularly keen to see ideas that appeal to girls. It’s 

always difficult to generalise but here are some insights that could help you understand our audience: 

Constantly connected 

Teenagers stay in constant contact. Unsurprisingly, mobile phones are more important to them than any other device, even TV. Girls are 

particularly prolific communicators; in 2012, 12-15 year old girls sent 35% more texts than boys (Ofcom, 2012). 

Visual self-expression 

Teenagers can be highly visual, and use photography and video to express feelings, forge friendships and share their lives (Boyd, 2014). 

Examples include the appeal of emojis to express emotion; Vine to easily edit and share video and Snapchat or Instagram to share photos. 

Developing identities 

Teenagers become increasingly conscious of shaping the way they present themselves to others (Sherbert research for BBC, 2013). Social 

media now plays a key role in how they maintain and develop their identity (Doster, 2013). For example, the photos that they stage, share 

and comment on help them express not only who they are but also how they want to be seen. Some also use social media to connect with 

cultural icons and earn kudos from their peers. 

The full document can be found at

http://www.bbc.co.uk/partnersandsuppliers/connectedstudio/events/coding.html

 Our idea

We wanted to come up with an idea that would somehow combine the things that teenagers enjoy using in technology while also inspire an interest in the creation of technology. 

We came up with an app that would allow users to create a photo story or small comic using their own pictures, videos and sounds and adding speech bubble, text, graphics, transitions etc. These stories could then be passed on and added to by their friends.

The coding element would come in because the feature set would initially be full but basic. The stories would be created using a drag and drop interface which also output real, readable and editable code allowing the user to extend the features of the app to acheive the effect they want.

For example initially we might provide 3 text colours for speech bubbles black, white and red, but if you really wanted green text you could go into the code editor and add this option. The initial code would be well commented and simple enough that this basic type of extension would be easy to accomplished by copying and pasting an existing line and just change the relative part of the line, ideally getting people coding without even realised that that is what they are doing. The hope is that this would lead to the users adding more complex features to their stories.

Another element of this that we hoped would encourage the use of code would be to see a story one of your friends had made with a really nice feature in it that your version doesn’t have. If you want that feature you either have to add it in yourself or ask your friend to share it with you. This sharing of features would itself expand the users understanding of coding and the creative possibilities.

Audience Feedback

In the afternoon we had the chance to put our idea forward to a panel of genuine young people, luckily they liked the idea and gave us plenty to think about, both for our pitch later and for things to think about if our idea gets taken forward. This included thinking about how ownership of a story would work and pass on through each page, and the variety of ways it could be used, including as a story board or inspiration board for sharing ideas for a theatre production.

The pitches

At the end of the day each team, 36 in all, did a 2 minute pitch of their ideas. It was interesting to see how many teams had independently come up with similar ideas and the range of ideas that were put forward.

Some of the ideas that were pitched included

– a secret message that is sent to you by a friend,  you have to change the code to uncover the message

– a dream house creating tool

– a Hackstage Pass where you unlock content and experiences from musicians by completing coding tasks and challenges,  presented by a team including CoderDojoScotland @CoderScot

– using magic tricks to teach coding concepts

The next stage

Following the Creative Studio 10 teams are invited to the Build Studio, a 2 day event where the selected ideas are developed further and refined. If we are selected I’m sure you’ll be looking forward to another blog post on that event.

read more