Interactive Learning Document Format Reference

互动学习文档格式Interactive Learning Document Format Reference

一种互动学习文档的游戏，让读者与代码互动，并混合丰富的HTML内容。它的文件格式是一个包，包含Swift源代码、HTML内容、资产如CSS和图片、清单文件。An interactive learning document is a kind of playground that lets the reader interact with code mixed with rich HTML content. Its file format is a package that contains Swift source code, HTML content, assets such as CSS and images, and a manifest file.

例如，一个例子文档的目录结构如下：For example, the directory structure of an example document is as follows:

• My Example.playground

  • contents.xcplayground

  • Documentation/

    • style.css

    • Art/

      • cow.png

      • dog.jpg

    • section–1.html

    • section-3.html

  • Resources/

    • data.json

    • background.png

  • section–2.swift

  • section–4.swift

这个清单是名为contents.xcplayground的XML文件，在包的最顶部。The manifest is an XML file named contents.xcplayground at the top level of the package. Example contents.xcplayground file shows the manifest file for an example playground.

Listing 2-1  Example contents.xcplayground file

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<playground version='3.0' sdk='macosx' allows-reset='YES'>

    <sections>

        <code source-file-name='section-1.swift'/>

        <documentation relative-path='section-2.html'/>

        <code source-file-name='section-3.swift'/>

        <documentation relative-path='section-4.html'/>

    </sections>

    <timeline fileName='timeline.xctimeline'/>

</playground>

清单包含XML元素，描述如下。The manifest contains the XML elements described below.

playground

XML文件根元素Root element of the XML file.

包含一个章节元素和一个时间线元Contains one sections element and one timeline element.

属性Attributes

版本version

Required. 文件格式版本。使用3.0做为其值。File format version. Use 3.0 as the value.

重点：总是检查版本数字。互动学习文档文件格式是期望继续进化。之后的文件格式版本可能有不同的元素，属性或结构。Important: Always check the version number. The interactive learning document file format is expected to continue to evolve. Future versions of this file format might have different elements, attributes, or structure.

sdk

Required. playground要使用SDK。OS X使用macosx或者iOS使用iphonesimulator——Xcode总是使用最新的选中的SDK的版本。SDK used by the playground. Use macosx for OS X or iphonesimulator for iOS—Xcode always uses most recent version of the selected SDK.

允许重置allows-reset

指示是否用户可以编辑playground并重置到原始状态。使用yes激活重置，默认为no。Indicates whether users can edit the playground and then reset it to its original state. Use yes to enable resetting or no (the default).

如果可重置，当用户编辑一个playground，Xcode保存一个源代码文件的副本到包的顶层，添加-original后缀到文件名。这些原始文件不会出现在清单中，不能编辑。If resetting is enabled, when the user edits a playground, Xcode saves a copy of the original source code files at the top level of the package, adding the suffix -original to their filenames. These original files do not appear in the manifest and shouldn’t be edited.

章节sections

列出文档章节List of the sections of the document.

包含文件和代码元素Contains documentation and code elements.

文档documentation

HTML文档章节HTML documentation section.

每个HTML文档章节是在本身的网页视图渲染的。这意味着，例如，在一个章节运行的JS，只可以访问该JS的一些章节的DOM结构。Each HTMS documentation section is rendered in its own web view. This means, for example, that JavaScript running in one section can access the DOM structure of only that some section.

属性Attributes

相对路径relative-path

Required. HTML文件路径，相对于文档文件夹在包的顶层。Path to the HTML file relative to the Documentation folder at the top level of the package.

所有HTML文件和资源例如图片和CSS文件需要这些文件存储在文档文件夹。你可以组织文档文件夹和子文件夹。All HTML files and resources such as images and CSS files that are used by the those files are stored in the Documentation folder. You can organize the Documentation folder with subfolders. 

代码code

Swift源代码章节Swift source code section.

代码章节的文件名是不能确保用户编辑文档后保存在Xcode。The file names of code sections are not guaranteed to be preserved after the user edits the document in Xcode.

属性Attributes

源文件名source-file-name

Required. Swift源文件的文件名File name of the Swift source file.

所有Swift源文件存储在包顶层。All Swift source files are stored at the top level of the package. 

资产如图片和输入数据，用于Swift代码，存储在包顶层的资源文件夹。Assets such as images and input data that are used by the Swift code are stored in the Resources folder at the top level of the package.

风格style

展示代码片段的风格Display style for the code fragment.

为在一个关联区域展示代码，使用setup作为值。To display the code in a disclosable region, use setup as the value.

时间线timeline

Xcode时间线信息。这个元素和相关联文件是Xcode填充，基于playground的时间线，且不能手动编辑。Xcode timeline information. This element and the file it refers to are populated by Xcode based on the items in the playground’s timeline, and shouldn’t be edited by hand.

资料：

Playground动手玩 （在OSx 10.9.3 、Xcode 6 beta环境下测试playground，只能用Swift语言） - @Bailey