Chapter 2. Write How You Want

When you are using Atlas to write your book, you have the option of writing in the wiki interface or locally on your own computer. This chapter covers each of those scenarios. As you write your book, you can jump back and forth between the two writing environments. As long as you are saving in the web interface or using git to push and pull from your local machine, you’ll always be in sync.

Get Your Gravatar

You may notice that some users have personal icons in the Changes and Collaborators sections of Atlas. Those image icons are pulled in from Gravatar, based on the user’s email address. Set up your Gravatar to get a more personalized icon.

Working in the Atlas Wiki

If you’ve used a wiki before, you will find the Atlas interface to be very familiar. In the following sections, you’ll learn how to create and edit new files in the wiki interface.

Creating New Files

When you create your book in Atlas, it will have no files, as shown in Figure 2-1.

A screenshot of the Atlas dashboard for a new project
Figure 2-1. When you create a new book in Atlas, you start off with a blank slate

You can create your first file by clicking on Open Editor. Atlas will recognize that your book has no files, and you will be prompted to create one. Click “Create your first file” and name the file, as shown in Figure 2-2.

A screenshot of creating an new file in the Atlas user interface
Figure 2-2. Create your first file

Once you’ve created the file, you’re ready to start writing!

Working with AsciiDoc Text in Atlas

When you’re working in the Atlas wiki interface, you will need to write in AsciiDoc.[1] See Chapter 4 for an introduction to AsciiDoc markup.

The Atlas wiki editor works just as you’d expect. Use the buttons to insert simple AsciiDoc markup. For example, Figure 2-3 shows what happens when you click the H1 button.

A screenshot of the Atlas wiki interface
Figure 2-3. Use the Atlas wiki interface to write in your web browser

Once you’ve entered some text, click Save and your changes will be committed to a git repository that is created automatically each time you start a new book. Optionally, you can enter a log message before you click Save, and it will be included with the commit to the git repository, as show in Figure 2-4. Read more about making the most of your git repository in “Working Locally” and Chapter 5.

A screenshot showing an example of entering a log message in the Atlas
Figure 2-4. It’s good practice to add a meaningful log message

Note also that you can use the File Manager drop-down to jump to other files or to create new ones.

Adding Images via the Atlas Interface

You can upload images to your book directly in the Atlas wiki interface. Click on Image manager and then select Choose File and finally Upload, as shown in Figure 2-5.

A screenshot of the Atlas image uploader
Figure 2-5. Upload your images within Atlas

Once you’ve uploaded your image, Atlas will generate a thumbnail preview of that image, which you can see at any time by bringing up the Image manager.

At this time, if you upload an image via git, the image will not have a thumbnail preview within the Image manager.

You can also use the Image manager to insert the AsciiDoc reference to that image:

  1. Place the cursor where you’d like to insert the image within the text.
  2. Click on Image manager.
  3. Select the thumbnail preview of the image you’ve uploaded and click Insert (Figure 2-6).
A screenshot showing how to highlight and insert a reference to an image from the Atlas image uploader
Figure 2-6. You’ve uploaded the image; now reference it within your document

Once you click insert, Atlas will add AsciiDoc markup that looks something like the following to your document:

image::images/insert_image_asciidoc.png[]

Read more about figure and image markup in “Figures and Other Images” in Chapter 4.

Tracking Changes in Atlas

Each time you save a change in the wiki interface or use git to push a change to your repository (as described in “Committing and Pushing”), Atlas displays that change on the Changes tab.

A screenshot of how Atlas displays edits to the text. Added text has a green background. Deleted text is crossed out and has a red background.
Figure 2-7. An Atlas change box shows additions and deletions made to the text

Figure 2-7 shows a change that was saved to the repository via a git push. In this change notification box, Atlas displays the author who made the change along with the log message used during git commit. If the author were to use the Save button on the wiki interface (instead of git), as explained in “Working with AsciiDoc Text in Atlas”, the change would be captured and displayed in the same way.

When collaborating in the Web editor, make sure to coordinate with others to ensure that only one person is editing a specific document at a time. If two people are saving a document simultaneously, they may overwrite each other’s changes.

Working Locally

Atlas sits on top of a git repository, giving you the flexibility to write how and when you want. For example, suppose you have a long flight and want to write edit on the plane. No problem—just pull down your book files, make your changes locally, and then push them back up when you’re connected to the Internet again. Or perhaps you’d rather skip the wiki interface entirely and work on your local machine exclusively. That’s fine too.

Cloning Your Book

In order to work locally, you will need to have git installed on your machine. The following section describes a few basic git commands to get you up and running, but see Chapter 5 for more details around using git with Atlas.

Once you have git installed, click on the Admin tab in the Atlas interface to retrieve your git repository URL, as shown in Figure 2-8.

A screenshot of the Admin tab in Atlas showing the git URL
Figure 2-8. Grab your git repository URL from the Admin tab

Now that you have the URL, you can use git to clone it to your computer. Use the git clone command and enter your Atlas password. When you clone the repo, you can optionally add the name of the directory, like so:

$ git clone https://jhosman%40oreilly.com@atlas-server.oreilly.com/git/1230000000065.git
   getting_started_with_atlas/

Cloning into getting_started_with_atlas...
remote: Counting objects: 338, done.
remote: Compressing objects: 100% (337/337), done.
remote: Total 338 (delta 136), reused 0 (delta 0)
Receiving objects: 100% (338/338), 4.10 MiB | 534 KiB/s, done.
Resolving deltas: 100% (136/136), done.

The clone command will download all of the files into a directory named getting_started_with_atlas, and that directory is now under version control with git.

All of the examples in this guide use the command line git client. If the command line is not for you, there are several GUI git clients available for Windows, OS X, and Linux.

Committing and Pushing

Now that you’ve got a local checkout of your project, you can open and edit the .asciidoc file. As explained in Chapter 4, AsciiDoc is a text-based markup language. You can use any text editor to edit the files. Figure 2-9 shows edits being made to this chapter in TextMate, a text editor for the Mac.

A screenshot of an AsciiDoc file in TextMate
Figure 2-9. Editing an AsciiDoc file in TextMate

Now it’s time to commit the changes to the git repo. You can include a log message with -m. The -a means to include all changes.

$ git commit -a -m'added section on interfacing with the Atlas git backend'
[master 0e487ee] added section on interfacing with the Atlas git backend
 3 files changed, 46 insertions(+), 6 deletions(-)
 create mode 100644 images/editing_in_textmate.png

Finally, push your committed changes:

$ git push origin
Counting objects: 11, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 54.03 KiB, done.
Total 7 (delta 4), reused 0 (delta 0)
To https://adam%40oreilly.com@atlas-admin.oreilly.com/git/1230000000065.git
   ffb554d..90fd00f  master -> master

Now if you look in the Altas web interface, you will see the changes that you made locally reflected in the wiki interface.

Fetching and Pulling

You can also use git to pull down changes that were made in the wiki environment or by other contributors. There are two ways of downloading changes. One way is to use fetch followed by merge, as in this example:

$ git fetch
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From https://atlas-admin.oreilly.com/git/1230000000065
   cd86112..cba41ff  master     -> origin/master

fetch downloads the changes. Now use merge to bring your local files up to date:

$ git merge origin
Updating cd86112..cba41ff
Fast-forward
 ch02.asciidoc |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

Alternatively, you can use pull, which downloads the changes and merges them in with a single command:

$ git pull
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 6 (delta 4), reused 0 (delta 0)
Unpacking objects: 100% (6/6), done.
From https://atlas-admin.oreilly.com/git/1230000000065
   cba41ff..a972d49  master     -> origin/master
Updating cba41ff..a972d49
Fast-forward
 ch02.asciidoc |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

Using push and pull to interface with your Atlas repo is the just the beginning of what you can do with git. Check out Git Reference andChapter 5 to learn what else is possible.

Resolving Conflicts

When you use git merge or git pull, git will attempt to combine all changes into one document. Sometimes, however, git will fail to combine the text and your AsciiDoc file will have a conflict. This situation may arise if, for example, two authors try to push changes to the same line of text. Conflict resolution is beyond the scope of this document, but the Git User’s Manual has an excellent overview of git conflicts and how to resolve them.



[1] Atlas supports Markdown for less technically complex text. Ask your editor if Markdown is a good fit for your project.