Documentation

sam vs. ScML

The following describes key differences between ScML and sam and provides some resources for working with ScML.

Differences

The central XML file in the Well-Formed Document Workflow (WFDW) is the ScML file. Indicated by the .scml extension, this file includes all the information available for a publication. IDs, links, and other metadata are contained within ScML files; these files are used to produce e-books (.epub and .mobi) through the Digital Hub. ScML files can also be converted to HTML files or Word documents.

Another file type crucial to the WFDW is Scribe Abbreviated Markup (sam). Lowercase letters are always used to indicate sam files, as this visually demonstrates to the user that these files are diminutive in comparison to the robust ScML files. It is an easier markup in both the refined and unrefined versions, its simplicity allowing for adjustments and modifications to be applied quickly. A sam file is always transitional and is never the final goal of a file conversion. These files are created during conversions in the Digital Hub from Word documents to ScML or InDesign Tagged Text, for example. They are also an important part of the process of moving from InDesign’s XML output to ScML and e-books.

These are some key differences between ScML and sam:

  • Purposes of sam and ScML. A sam file is always transitional, encountered when converting from one file format to another, such as ScML, IDTT, or Word documents. It is a useful file type to apply basic adjustments, but it is never the final product. While ScML is the central, archival XML file in the WFDW, sam solves some of the technical limitations of Word and InDesign. Because of its simplified markup, sam is more nimble in adapting to the unique behaviors of these programs.
  • IDs. A sam file may contain page IDs if created using Scribe’s processes for extracting content from InDesign, but only an ScML file will contain chapter, cross reference, and index IDs.
  • Structure Tags. In sam, structure is a paragraph style, used to contain comments about structure tags, such as {~?~ST:begin chapter} or {~?~ST:begin sidebar}. This type of comment is used to retain this information in programs like Word and InDesign, which do not have the capability of using division tags. In ScML, these paragraphs are translated into true XML markup, wrapping content in <chapter>, <sidebar>, or other division tags.
  • Commenting Out Content. Content should never be commented out from a sam file. Text that has been commented out will be excluded from any file transformation done within the Digital Hub. For example, print relics may need to be excluded from an e-book version while still being retained in the archival ScML file. Since sam files are always transitional, all content should be retained and available for the archival ScML and only commented out in anticipation of a file conversion from that format.