Submitting and Formatting

Submissions Process

The standard submissions process is as follows:

1. Fork the GitHub repository
2. Checkout the fork (git clone http://github.com/<yourusername>/Perl-Advent) and enter that dir (cd Perl-Advent)
3. In your checkout switch to the branch for this year. For example, for 2016, you should switch to the y2016branch (git checkout y2016)
4. Create a file inside the submissionsfolder for the year you're working on (è.g. vim 2016/submissions/Foo.pod) and write your article in it
5. Commit your work (git add Foo.pod, git commit -m 'something, git push)
6. On the GitHub website create a Pull Request.

Once your article has been scheduled for publication it will be moved to the articles/yyyy-mm-dd.pod location. You should feel free to edit this on your fork and make further changes.

File Format

The file format of the article is standard pod with some simple additions. Notable changes include:

• Use of L<Module::Name> to automatically link to a module on metacpan
• Allowing =for html or =begin html to use verbatim HTML that will be rendered out directly

The pod file MUST use UNIX style line endings. Other line ending formats are not supported (todo: fix this)

The Header

Each file starts with a simple RFC822-style header on the first line that must be separated from the rest of the article by at least one blank line.

Title: This is the title that will be displayed
Topic: Foo::Bar
Author: Mark Fowler <[email protected]>

The Topicshould be the name of the module the article is about. The Author should contain an email address in <...> and that email address should have a gravitar icon associated with it. (Both of these however are optional)

The Footer

Each article should end with a standard see also footer.

=head1 SEE ALSO

=for :list
 * L<Module>
 * L<Some::Other::Module>
 * L<http://example.com/>

Note the use of the pod-weaver style for list (which is preferred). The first linked item should be the module this article is concerned with (I.e. The same thing that's in the Topicin the header.) Other links should be the name of modules or websites you've mentioned in the article or links to further documentation or articles on the topic on the web.

Code Blocks

Code blocks work like they do in standard pod: Starting the line with whitespace renders it as code.

The C<ls> command gives you a directory listing:

    bash$ ls

It's very handy!

The advent calendar also supports multiple forms of syntax highlighting that you should use for code blocks. All Perl blocks should start with an extra #!perlline to denote that the contents is Perl code (this line will be removed when it's rendered out)

 #!perl
 #!/usr/bin/perl
 use strict;
 use warnings;
 print "Hello World\n";

For other languages we need to invoke the vim highlighter

#!vim javascript
$("#foo").text("Hello World");

Using Images

Images are simply embedded using standard html formatting

=for html
   <center><img etc="foo.png" width="800" height="600"></center>

The image tag should be retina quality. This means that you should include width and height tags and the image file should be twice as large as the values in those tags (i.e. The foo.png file shown in the above example would have dimensions of 1600x1200.)

Please be considerate of download size when creating images. We would like them to be no more than a few hundred kilobytes at most.

The image files themselves should be placed in the shared/staticdirectory for each year (e.g. 2016/shared/static/foo.png) - when the advent calendar is built the calendar will copy these images into the same directory as the generated HTML.

JavaScript

You can add JavaScript to the page in a similar manner to the images above.

=for html
  <script src="foo.js"></script>

And the create the 2016/shared/static/foo.jsfile. For complicated JavaScript it's recommended you use an IFRAME

  =for html
     <IFRAME src="foo.html" width="100%" height="400"></IFRAME>

And have that frame load the JavaScript

However: IFRAMEs and JavaScript are very unlikely to work in a RSS reader, so you need to take steps to cope with this. You should probably use the =for web_onlyand =for rss_onlyescapes instead of =for html

  =for rss_only
     <p>Please visit the <a href="http://perladvent.org/2016/2016-12-01.html"> article on the web"> to see.the really cool thingy</p>

  =for web_only
    <IFRAME src="foo.html" width="100%" height="400"></IFRAME>

Rendering

To check that your article renders correctly you should install the WWW::AdventCalendar module from the CPAN. With this you can render the entire advent calendar in a few seconds

 ˜/perl-advent/2016$ advcal -c advent.ini --today=2030-01-01

If you place your article in the articles directory and give it a ymd style name (e.g. 2016-12-01.pod) then it will be rendered as part of the build process

(Todo: switch to render something from the submissions directory)