com.io7m.minisite 1.0.0 Documentation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1 Package Information ................................................... pkg
    1.1 Orientation ........................................... pkg.orientation
    1.2 Installation .............................................. pkg.install
    1.3 Platform Specific Issues ................................. pkg.platform
    1.4 License ................................................... pkg.license
  2 Usage ............................................................... usage
    2.1 Maven Plugin Usage ........................................ usage.maven


1 Package Information [id: pkg]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  1.1 Orientation ............................................. pkg.orientation
    1.1.1 Overview ................................... pkg.orientation.overview
  1.2 Installation ................................................ pkg.install
    1.2.1 Source compilation ............................... pkg.install.source
    1.2.2 Maven ............................................. pkg.install.maven
  1.3 Platform Specific Issues ................................... pkg.platform
  1.4 License ..................................................... pkg.license


1.1 Orientation [id: pkg.orientation]

1.1.1 Overview [id: pkg.orientation.overview]

1     The com.io7m.minisite package implements a trivial replacement for the
      Maven site plugin.

1.2 Installation [id: pkg.install]

1.2.1 Source compilation [id: pkg.install.source]

1     The project can be compiled and installed with Maven [url:
      http://maven.apache.org]:

2     $ mvn -C clean install

1.2.2 Maven [id: pkg.install.maven]

1     Regular releases are made to the Central Repository [url:
      http://search.maven.org/#search%7Cga%7C1%7Ccom.io7m.minisite].

2     All io7m.com [url: http://io7m.com] packages use Semantic Versioning [0],
      which implies that it is always safe to use version ranges with an
      exclusive upper bound equal to the next major version - the API of the
      package will not change in a backwards-incompatible manner before the
      next major version.

1.3 Platform Specific Issues [id: pkg.platform]

1     There are no known platform-specific issues.

1.4 License [id: pkg.license]

1     All files distributed with the com.io7m.minisite package are placed under
      the following license:

      1.4.2.2 License
      ───────────────

      Copyright © 2017 <code@io7m.com> http://io7m.com

      Permission to use, copy, modify, and/or distribute this software for any
      purpose with or without fee is hereby granted, provided that the above
      copyright notice and this permission notice appear in all copies.

      THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
      WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
      MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
      ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
      WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
      ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
      OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


2 Usage [id: usage]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Contents
  ─────────────────────────────────────────────────────────────────────────────
  2.1 Maven Plugin Usage .......................................... usage.maven
    2.1.1 Design ........................................... usage.maven.design
    2.1.2 Example ......................................... usage.maven.example


2.1 Maven Plugin Usage [id: usage.maven]

2.1.1 Design [id: usage.maven.design]

1     The plugin is designed to produce an extremely simple, static,
      single-page, XHTML 1.0 Strict site with no Javascript. The plugin assumes
      the existence of a 64x64 PNG file at /icon.png.

2.1.2 Example [id: usage.maven.example]

1     The following is a simple example of how to use the plugin:

      2.1.2.2 Example
      ───────────────

      <build>
        <plugins>

          <!-- Disable the existing maven-site-plugin -->
          <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.6</version>
            <executions>
              <execution>
                <id>default-site</id>
                <phase>none</phase>
                <goals>
                  <goal>site</goal>
                </goals>
              </execution>
            </executions>
          </plugin>

          <plugin>
            <groupId>com.io7m.minisite</groupId>
            <artifactId>com.io7m.minisite.maven_plugin</artifactId>
            <version>0.0.6</version>
            <executions>
              <execution>
                <id>minisite</id>
                <phase>site</phase>
                <goals>
                  <goal>generateSite</goal>
                </goals>
                <configuration>
                  <overviewFile>src/site/resources/overview.xml</overviewFile>
                  <featuresFile>src/site/resources/features.xml</featuresFile>
                  <documentationFile>src/site/resources/documentation.xml</documentationFile>
                  <changelogFile>README-CHANGES.xml</changelogFile>
                  <changelogFeedEmail>contact@io7m.com</changelogFeedEmail>
                  <outputDirectory>/home/rm/git/com.github/io7m/minisite/com.io7m.minisite.documentation/target/minisite</outputDirectory>
                  <resourcesDirectory>${project.base.directory}/src/site/resources</resourcesDirectory>
                  <cssGenerateDefault>true</cssGenerateDefault>
                  <cssStyles>
                    <cssStyle>minisite.css</cssStyle>
                    <cssStyle>example0.css</cssStyle>
                    <cssStyle>example1.css</cssStyle>
                  </cssStyles>
                </configuration>
              </execution>
            </executions>
            <inherited>false</inherited>
          </plugin>

        </plugins>
      </build>




3     By default, the maven-site-plugin [url:
      https://maven.apache.org/plugins/maven-site-plugin/] is bound to the
      Maven site lifecycle phase, so it's generally preferred to disable the
      plugin by explicitly binding it to the none phase. The minisite plugin is
      intended for use with multi-module builds and is designed to run at most
      once for the parent module, in contrast to the once-per-module execution
      model of the maven-site-plugin. It's therefore recommended to set
      inherited to false as shown so that the plugin won't execute for any
      child modules.

4     The overviewFile parameter specifies an XHTML file that will be inserted
      into the overview section of the generated site.

5     The featuresFile parameter specifies an XHTML file that will be inserted
      into the features section of the generated site.

6     The changelogFile parameter specifies an XML changelog in changelog [url:
      http://io7m.github.io/changelog] format that will be converted into XHTML
      for the generated site. If no file is specified, no changes section will
      be generated.

7     The changelogFeedEmail parameter the email address that will be used when
      generating an RSS feed for the changelog.

8     The outputDirectory parameter specifies the directory to which site files
      will be generated, and resources copied. This parameter is optional and
      defaults to {project.build.directory}/minisite.

9     The resourcesDirectory parameter specifies the directory from which site
      resources will be copied copied. This parameter is optional and defaults
      to {project.base.directory}/src/site/resources.

10    The cssGenerateDefault parameter specifies that the plugin should copy a
      default CSS style to the output directory. The parameter is optional and
      defaults to true.

11    The cssStyles parameter specifies a list of CSS styles that should be
      imported by the generated site.

12    The documentation parameter specifies documentation. It takes a list of
      DocumentationItem values as parameters. Each DocumentationItem specifies
      a name and a list of DocumentationFormat values. Each DocumentationFormat
      value specifies a format name and a path. The usage example above
      specifies a single documentation item that has three formats: Single-page
      XHTML placed at /documentation/index.xhtml, multi-page XHTML placed at
      /documentation/index-m.xhtml, and plain text placed at
      /documentation/main.txt.


Footnotes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[0]   http://semver.org [url: http://semver.org]

