Skip to content

Latest commit

 

History

History
61 lines (42 loc) · 3.56 KB

experienced_github_users.adoc

File metadata and controls

61 lines (42 loc) · 3.56 KB

A quick workflow for experienced Git, GitHub, and Asciidoc users

This is the general workflow to contribute to the WGFAST convention documents for those familiar with Git and GitHub.

Table of Contents

Git Workflow

Fork-Branch-Pull Request

  1. In GitHub, fork the ices-eg\wg_WGFAST repository to your own GitHub account.

  2. Clone the forked repository to your local computer.

  3. Create a branch for your edits and work in that branch. A good naming convention for your branch would be xx_edits where xx is your initials.

  4. Edit the AsciiDoc files. Stage, commit, and push the edits to the working branch in your remote repository.

  5. In GitHub, submit a pull request from your working branch to the master branch of the ices-eg\wg_WGFAST repository.

This is a good blog post on the Git Fork-Branch-Pull Request workflow. (Hat tip: Wu-Jung Lee)

Please ask first before starting on any significant edits, otherwise you risk spending a lot of time working on something that the convention coordinators might not want to merge into the project. You can contact the convention coordinators by opening an issue in the issue tracker.

The Sourcetree program for Windows and Mac is a useful tool for working with Git repositories. TortoiseHg for Windows and Linux is another option. You can of course also use the Git command line interface.

AsciiDoc tools

Real-time rendering of the document

When editing the convention files, it is useful to see the rendered version of the documents as changes are made. Ways to achieve this are explained at Editing AsciiDoc with Live Preview. We find that Asciidoctor.js Live Preview works well, but note that it does not currently do the bibliography in the AcMeta document.

Three of the modern text editors/IDEs listed at Editing AsciiDoc with Live Preview, AsciidocFX, Atom and Brackets, are explained in the Text editors/IDEs help file.

Off-line rendering of the document

This requires installing AsciiDoctor onto your computer and can be somewhat complicated. Instructions are here. Remember to also install the asciidoctor-bibtex extension. Once all installed, the conventions can be rendered in several formats with these commands.

HTML files

Generates one or more files (images are kept separate):

asciidoctor -r asciidoctor-bibtex acmeta.adoc
HTML (single file)

For a single html file (including the images, which makes it easier to distribute):

asciidoctor -r asciidoctor-bibtex --backend html5 -a data-uri acmeta.adoc
PDF

Note that the asciidoctor-mathematical extension must be installed to get the mathematical equations correctly rendered:

asciidoctor-pdf -r asciidoctor-bibtex  acmeta.adoc
Word (.docx)

First convert to docbook format, then install and use pandoc to convert to Word:

asciidoctor -r asciidoctor-bibtex --backend docbook acmeta.adoc
pandoc --from docbook --to docx -o acmeta.docx acmeta.xml