Name

Dita::GB::Standard - The Gearhart-Brenan Dita Topic Naming Standard.

Synopsis

The GB Standard is a means of naming Dita topic files to enable global collaboration through uncoordinated content sharing.

The GB Standard creates a human readable, deterministic file name which depends solely on the content to be stored in that file. Such file names are guaranteed to differ between files that contain differing content while being identical for files that contain identical content by the use of an md5 sum in the file name.

The GB Standard name looks like this:

human_readable_part_derived_from_content + _ + md5_sum_of_content + extension

The human readable part from content is derived solely from the content of the file by interpreting the file content as Unicode encoded as utf8, then:

- replacing instances of xml tags with underscores

- replacing all characters other than a-z,A-Z,0-9 with underscores

- replacing runs of underscores with a single underscore

- removing any leading or trailing underscores

- truncating the component if it extends beyond $nameFromStringMaximumLength characters.

The original file name for the content is not considered as part of the content of the file and so plays no part in choosing the GB Standard name for that content.

If the file contains a title tag then only the content of the title tag is processed as described above to obtain the human readable component of the file name. If any of the following Dita tags are found in a source file which also contains a title tag then the following codes are prefixed to this file name as well:

Code      Tag
bm_       bookmap
c_        concept
r_        reference
t_        task

The md5 sum component of the file name is calculated from the content of the file and presented as lowercase hexadecimal.

The file extension component is obtained from: https://en.wikipedia.org/wiki/List_of_filename_extensions

Thus if a dita file has content:

<concept>
  <title>abc 𝝰𝝱𝝲</title>
  <conbody/>
</concept>

then the GB Standard name for the file is:

c_abc_8551cffdb92932637d952e04447783c8.dita

If the option to present the md5 sum as five letter English words is chosen then the standardized name for this content becomes:

c_abc_Plume_VApoR_CaPER_eqUAl_qUAIL_saInT_mEdia_Irony.dita

Benefits

The file names generated by the GB Standard can be exploited in numerous ways to simplify the creation, conversion, management and sharing of large repositories of documents written to the Dita standard:

Parallel Processing

Complex long running document transformations can be speeded up by running the transformations in parallel.

The file name generated by the GB Standard is unique when computed by competing parallel processes so files that have the same name have the same content and can be safely overwritten by another process without attempting to coordinate names between processes. Likewise files that have different names are guarenteed to have different content and so can be written out without checking for an existing file of that name.

Alternative systems relying on coordination between the parallel processes to choose names to avoid collisions and reuse identical content perform ever more badly as the number of files increases because there are ever more files to check for matching content and names. Coordination between parallel processes stops the processes from running fully in parallel. Conversely, eliminating the need for coordination between parallel processes allows each process to run more fully in parallel.

As a consequence, the GB Standard enables parallel Dita conversions to scale effectively.

File Flattening

Files are automatically flattened by the GB Standard as files with the same content have the same name and so can safely share one global folder without fear of name collisions or having multiple names for identical content.

Testing

The name of each file reflects only its content making it easier to write tests for software build around the GB Standard: it is no longer necessary to test that the content of the file is as expected when it is sufficent just to test the base name of the file.

One could, of course, compute the md5 sum of the file easily during testing but: the fact that one is computing such a sum at all shows just how useful such a sum is, which implies that it should be the one and only piece of meta data encoded in the file name. All othermeta data should reside within the file rather then being encoded in the file name so that said meta data is not destroyed by renaming the file.

Mixed Multiple Conversions

When converting documents to Dita it is a standard practice to perform the conversion in batches by source document type, perhaps html files first, then docbook files, then word files. Thus leaves the problem of merging the results into one corpus after each individual conversion. The GB Standard resolves this problem by guaranteeing the uniqueness of the converted files allowing them to be merged into one results folder without collisions.

No Relative Paths in References

If all the topic files share one global folder there is no need for complicated path expressions in references such as:

<image href="../../../image{200B}files/size{200B}large/aaa.png"/>

Extended path names that are repeated across many references are, in effect, a form of boiler plate which can be avoided by applying this standard.

Relocating Dita References After Folder Restructuring

In the ideal implementation all files named with the GB Standard occupy one global folder. In circumstances where this is not possible, such files can easily be moved into sub folders without fear of collisions, although, any Dita references between such files might have to be updated. This update is easily performed because only the path component has to be updated and the value of the new path can easily be found by searching for the base component of the topic file name using a utility such as find. For a more efficient method, see Data::Edit::Xml::Xref.

Similar Files Tend To Appear Close Together In Directory Listings.

Imagine the user has several files in different folders all starting:

<title>License Agreement</title>

The GB Standard computes the human readable component of the name in a consistent way using only the contents of each file. Once the name has been standardized, all these files can be placed in one folder to get a directory listing like:

license_agreement_a6e3...
license_agreement_b532...
license_agreement_c65d...

This grouping signals that these files are potentially similar to each other and thus might be better merged into one shareable file.

As the GB Standard is applied to ever more such files, ever more such matches occur.

Copying And Moving Files For Global Interoperability

Users can copy files named using the GB Standard around from folder to folder without fear of collisions or duplication obviating the need for the time consuming checks and reportage otherwise required before performing such actions. The meta data in the "Companion File" can also be copied in a similar fearless manner.

If two users wish to share content: their files named using the GB Standard can be incorporated directly into the other user's file system without fear of collisions or duplicating content thus promoting global content sharing and collaboration of Dita content.

Guidization For Content Management Systems

Self constructed Content Management Systems using BitBucket, GitHub or Gitlab that rely on guidization to differentiate files placed in these repositories benefit immensely: the guid to use can be easily derived from the md5 sum sum in the GB Standard file name.

No need for authors to coordinate topic file names

The GB Standard is relevant to the administration of a production document corpus. A production corpus being a corpus of documents that is evolving over time under the control of an administrator.

If an author is developing a document from scratch, in splendid isolation, then, initially, the author might well wish to use topic file names of their own choice to contain their topics as this will speed their efforts.

For example, it is not uncommon for an author to create a file called:

introduction.xml

to hold the introduction to the new document they are writing.

At some point the system administrator will wish to incorporate the topic files comprising the new document produced by the author into the production corpus.

The chance that any of the file names that the author has chosen will conflict with the existing names in the production corpus as generated by the GB Standard is negligible. It is thus safe for the administrator to copy the author's topic files directly into the production corpus without renaming any of them. Sooner or later, however, the administrator might wish to run an automated scan of the entire production corpus to rename such recent additions to the GB Standard, to update all the references between these files that would otherwise be invalidated by such changes and thereby to clear the production corpus to make it ready to receive other new documents whose topic file names, being chosen by humans, would otherwise very likely conflict with existing topic file names already in the production corpus.

Thus clearing the production corpus by applying the GB Standard obviates the need for authors to coordinate the names of the files that they choose for their topics with those choosen by other authors allowing each author to proceed efficiently in isolated parallelism, spending more time writing and less time in meetings with other authors discussing their latest file naming strategy.

Using Dita Tags To Describe Content

The GB Standard encourages Dita users to use meta data tags to describe their documents so that content can be found by searching with grep rather than encoding file meta data in file names then searching for the required file using find. Such file names quickly become very long and unmanageable: on the one hand they need spaces in them to make them readable, but on the other hand, the spaces make such files difficult to cut and paste or use from the command line.

Cut And Paste

As there are no spaces in the files names created using the GB Standard such file names can be selected by a mouse double click and thus easily copied and pasted into other documents.

Conversely, one has to use cut and paste to manipulate such file names making it impossible to mistype such file names in other documents.

CSV files

Files named using the GB Standard can be safely included in .csv files because they have no spaces in them!

Automatic File Versioning

Files named to the GB Standard File names change when their content changes. So if the content of a file changes its name must change as well. Thus an attempt to present an out-of-date version of a file produces a file name that cannot be found.

Enhanced Command Line Processing

As file names named with the GB Standard do not have spaces in them (such as zero width space) they work well on the command line and with the many command line tools that are used to manipulate such files enhancing the productivity leverage that command line has always had versus graphical user interface processing.

Locating Files by Their Original Names Or Other Meta-Data

Each file produced by the GB Standard can have a "Companion File" of the same name but without an extension. The "Companion File" contains meta-data about the file such as its original location etc. which can be searched by grep or similar.

To find such a file use grep to find the "Companion File" containing the searched for content, paste that file name into the command line after entering any command such as ll and then press . followed by the tab key to have the shell expand it to locate the GB Standard file that corresponds to the located "Companion File". For example:

\\grep -r 'SR-dashboard-ds.png'

png_f940c7db293fe377e7d49c4e0c654cb2:  source => "/home/phil/r/pureStorage/docBook/download/OE_User_Guide/SRRBeta/images/screenshots/dashboard/SR-dashboard-ds.png",

ls png_f940c7db293fe377e7d49c4e0c654cb2.png

Use with AWS Simple Storage Service

Viewing files held in S3 is made much easier if they are all in one flat folder with uniqwue base names as there is no folder structure to navigate over a nework. Simply type the start of the G part, the Human Readdable Component, and press enter to see the possible candidates.

Companion File

Each file named using the GB Standard may be accompanied by a "Companion File" that contains meta data describing the file, said data formatted as a Perl data structure.

The name of the "Companion File" is obtained by removing the extension from the file named using the GB Standard.

As the content of the companion files is in plain text, such text is easy to search using grep or other textual search tools.

A common use of the companion file is to record the orginal file name and author of the content in question:

{source=>q(C:/my documents/dita files/content.dita),
 author=>q(A. N. Mouse),
}

Alternate File Names

Most operating systems allow the use of links to supply alternate names for a file. Consequently, users who wish to impose a different file naming scheme might care to consider using links to implement their own file naming system on top of the GB Standard without disrupting the integrity of the GB Standard.

For example: Xref produces Oxygen Project Files which provide a virtual hierarchical folder view of an otherwise flat folder.

Implementation

The GB Standard has been implemented as a Perl package at:

http://metacpan.org/pod/Dita::GB::Standard

Binary vs Utf8

Files that are expected to contain data encoded with utf8 (eg .dita, .xml) should use method names that start with:

gbStandard

Files that are expected to contain binary data (eg .png, .jpg) should use method names that start with:

gbBinaryStandard

The binary standard forms file names by prefixing the md5 sum value with the extension of the file in lower case and an underscore to prevent the long garbled file names that would otherwise be chosen if the normal standard were applied directly to naming such content and to group such files close together in directory listings.

Consequently, a png file with content:

q(\0abc\1)

will be represented by the name:

png_2786f1147a331ec6ebf60c1ba636a458.png

Documentation Copyright

The documentation for this module is dual licensed with the GNU Free Documentation License as well as the Perl Artistic Licence in the hope that this will encourage its further dissemination as a universal standard.

Description

The Gearhart-Brenan Dita Topic Naming Standard.

Version 20190901.

The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.

Make and manage utf8 files

Make and manage files that conform to the GB Standard and are coded in utf8.

gbStandardFileName($$%)

Return the GB Standard file name given the content and extension of a proposed file.

   Parameter   Description
1  $content    Content
2  $extension  Extension
3  %options    Various ingenious options designed by Micaela

Example:

if (1) {
  if (useWords)
   {ok 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(<<END, q(dita)) eq q(c_abc_Plume_VApoR_CaPER_eqUAl_qUAIL_saInT_mEdia_Irony.dita);
<concept>
  <title>abc 𝝰𝝱𝝲</title>
  <conbody/>
</concept>
END
   }
  else
   {ok 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(<<END, q(c_abc.dita)) eq q(c_abc_8551cffdb92932637d952e04447783c8.dita);
<concept xtrf="A">
  <title>abc 𝝰𝝱𝝲</title>
  <conbody/>
</concept>
END
   }
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardFileName)

gbStandardCompanionFileName($)

Return the name of the "Companion File" given a file whose name complies with the GB Standard.

   Parameter  Description
1  $file      L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> file name

Example:

ok 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(q(a/b.c)) eq q(a/b);

This method can be imported via:

use Dita::GB::Standard qw(gbStandardCompanionFileName)

gbStandardCompanionFileContent($)

Return the content of the "Companion File" given a file whose name complies with the GB Standard.

   Parameter  Description
1  $file      L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> file name

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbBinaryStandardCreateFile($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗖𝗼𝗻𝘁𝗲𝗻𝘁($c) eq $S;

  ok gbBinaryStandardCompanionFileContent($f) eq $S;                            # Check companion file content

  my $F = gbBinaryStandardCopyFile($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok gbBinaryStandardCompanionFileContent($C) eq $S;

  ok 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗖𝗼𝗻𝘁𝗲𝗻𝘁($F) eq $S;                                  # Check companion file content

  ok !gbBinaryStandardRename($F);                                               # No rename required to standardize file name

  gbBinaryStandardDelete($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardCompanionFileContent)

gbStandardCreateFile($$$%)

Create a file in the specified $Folder whose name is the GB Standard name for the specified $content and return the file name, A "Companion File" can, optionally, be created with the specified $companionContent

   Parameter   Description
1  $Folder     Target folder or a file in that folder
2  $content    Content of the file
3  $extension  File extension
4  %options    Options.

Example:

if (1) {
  my $s = q(abc 𝝰𝝱𝝲);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗿𝗲𝗮𝘁𝗲𝗙𝗶𝗹𝗲($d, $s, q(xml), companionContent=>$S);           # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbStandardCompanionFileName($f);                                      # Check companion file
  ok -e $c;
  ok readFile($c) eq $S;

  my $F = gbStandardCopyFile($f, target=>$D);                                   # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbStandardCompanionFileName($F);                                      # Check companion file
  ok -e $C;
  ok readFile($C) eq $S;

  ok !gbStandardRename($F);                                                     # No rename required to standardize file name

  gbStandardDelete($F);                                                         # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardCreateFile)

gbStandardRename($%)

Check whether a file needs to be renamed to match the GB Standard. Return the correct name for the file or undef if the name is already correct.

   Parameter  Description
1  $file      File to check
2  %options   Options

Example:

if (1) {
  my $s = q(abc 𝝰𝝱𝝲);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbStandardCreateFile($d, $s, q(xml), companionContent=>$S);           # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbStandardCompanionFileName($f);                                      # Check companion file
  ok -e $c;
  ok readFile($c) eq $S;

  my $F = gbStandardCopyFile($f, target=>$D);                                   # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbStandardCompanionFileName($F);                                      # Check companion file
  ok -e $C;
  ok readFile($C) eq $S;

  ok !𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗥𝗲𝗻𝗮𝗺𝗲($F);                                                     # No rename required to standardize file name

  gbStandardDelete($F);                                                         # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardRename)

gbStandardCopyFile($%)

Copy a file to the specified $target folder renaming it to the GB Standard. If no $Target folder is specified then rename the file in its current folder so that it does comply with the GB Standard.

   Parameter  Description
1  $source    Source file
2  %options   Options

Example:

if (1) {
  my $s = q(abc 𝝰𝝱𝝲);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbStandardCreateFile($d, $s, q(xml), companionContent=>$S);           # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbStandardCompanionFileName($f);                                      # Check companion file
  ok -e $c;
  ok readFile($c) eq $S;

  my $F = 𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗽𝘆𝗙𝗶𝗹𝗲($f, target=>$D);                                   # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbStandardCompanionFileName($F);                                      # Check companion file
  ok -e $C;
  ok readFile($C) eq $S;

  ok !gbStandardRename($F);                                                     # No rename required to standardize file name

  gbStandardDelete($F);                                                         # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardCopyFile)

gbStandardDelete($)

Delete a file and its companion file if there is one.

   Parameter  Description
1  $file      File to delete

Example:

if (1) {
  my $s = q(abc 𝝰𝝱𝝲);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbStandardCreateFile($d, $s, q(xml), companionContent=>$S);           # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbStandardCompanionFileName($f);                                      # Check companion file
  ok -e $c;
  ok readFile($c) eq $S;

  my $F = gbStandardCopyFile($f, target=>$D);                                   # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbStandardCompanionFileName($F);                                      # Check companion file
  ok -e $C;
  ok readFile($C) eq $S;

  ok !gbStandardRename($F);                                                     # No rename required to standardize file name

  𝗴𝗯𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗗𝗲𝗹𝗲𝘁𝗲($F);                                                         # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbStandardDelete)

Make and manage binary files

Make and manage files that conform to the GB Standard and are in plain binary.

gbBinaryStandardFileName($$)

Return the GB Standard file name given the content and extension of a proposed file.

   Parameter   Description
1  $content    Content
2  $extension  Extension

Example:

if (1) {
  if (useWords)
   {ok 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(qq(\0abc\1), q(png)) eq q(png_thInk_BUSHy_dRYER_spaCE_KNOwN_lepeR_SeNse_MaJor.png);
   }
  else
   {ok 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(qq(\0abc\1), q(png)) eq q(png_2786f1147a331ec6ebf60c1ba636a458.png);
   }
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardFileName)

gbBinaryStandardCompanionFileName($)

Return the name of the companion file given a file whose name complies with the GB Standard.

   Parameter  Description
1  $file      L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> file name

Example:

ok 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗡𝗮𝗺𝗲(q(a/b.c)) eq q(a/b);

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardCompanionFileName)

gbBinaryStandardCompanionFileContent($)

Return the content of the "Companion File" given a file whose name complies with the binary GB Standard.

   Parameter  Description
1  $file      L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> file name

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbBinaryStandardCreateFile($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok gbStandardCompanionFileContent($c) eq $S;

  ok 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗖𝗼𝗻𝘁𝗲𝗻𝘁($f) eq $S;                            # Check companion file content

  my $F = gbBinaryStandardCopyFile($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗺𝗽𝗮𝗻𝗶𝗼𝗻𝗙𝗶𝗹𝗲𝗖𝗼𝗻𝘁𝗲𝗻𝘁($C) eq $S;

  ok gbStandardCompanionFileContent($F) eq $S;                                  # Check companion file content

  ok !gbBinaryStandardRename($F);                                               # No rename required to standardize file name

  gbBinaryStandardDelete($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardCompanionFileContent)

gbBinaryStandardCreateFile($$$$)

   Parameter          Description
1  $Folder            Target folder or a file in that folder
2  $content           Content of the file
3  $extension         File extension
4  $companionContent  Contents of the companion file.

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗿𝗲𝗮𝘁𝗲𝗙𝗶𝗹𝗲($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok gbStandardCompanionFileContent($c) eq $S;

  ok gbBinaryStandardCompanionFileContent($f) eq $S;                            # Check companion file content

  my $F = gbBinaryStandardCopyFile($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok gbBinaryStandardCompanionFileContent($C) eq $S;

  ok gbStandardCompanionFileContent($F) eq $S;                                  # Check companion file content

  ok !gbBinaryStandardRename($F);                                               # No rename required to standardize file name

  gbBinaryStandardDelete($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardCreateFile)

gbBinaryStandardRename($)

Check whether a file needs to be renamed to match the GB Standard. Return the correct name for the file or undef if the name is already correct.

   Parameter  Description
1  $file      File to check

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbBinaryStandardCreateFile($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok gbStandardCompanionFileContent($c) eq $S;

  ok gbBinaryStandardCompanionFileContent($f) eq $S;                            # Check companion file content

  my $F = gbBinaryStandardCopyFile($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok gbBinaryStandardCompanionFileContent($C) eq $S;

  ok gbStandardCompanionFileContent($F) eq $S;                                  # Check companion file content

  ok !𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗥𝗲𝗻𝗮𝗺𝗲($F);                                               # No rename required to standardize file name

  gbBinaryStandardDelete($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardRename)

gbBinaryStandardCopyFile($$)

   Parameter  Description
1  $source    Source file
2  $target    Target folder or a file in the target folder

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbBinaryStandardCreateFile($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok gbStandardCompanionFileContent($c) eq $S;

  ok gbBinaryStandardCompanionFileContent($f) eq $S;                            # Check companion file content

  my $F = 𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗖𝗼𝗽𝘆𝗙𝗶𝗹𝗲($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok gbBinaryStandardCompanionFileContent($C) eq $S;

  ok gbStandardCompanionFileContent($F) eq $S;                                  # Check companion file content

  ok !gbBinaryStandardRename($F);                                               # No rename required to standardize file name

  gbBinaryStandardDelete($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardCopyFile)

gbBinaryStandardDelete($)

Delete a file and its "Companion File" if there is one.

   Parameter  Description
1  $file      File to delete

Example:

if (1) {
  my $s = qq(\0abc\1);
  my $S = q(Hello World);
  my $d = temporaryFolder;
  my $D = temporaryFolder;
  clearFolder($_, 10) for $d, $D;

  my $f = gbBinaryStandardCreateFile($d, $s, q(xml), $S);                       # Create file
  ok -e $f;
  ok readFile($f) eq $s;

  my $c = gbBinaryStandardCompanionFileName($f);                                # Check companion file
  ok -e $c;
  ok gbStandardCompanionFileContent($c) eq $S;

  ok gbBinaryStandardCompanionFileContent($f) eq $S;                            # Check companion file content

  my $F = gbBinaryStandardCopyFile($f, $D);                                     # Copy file
  ok -e $F;
  ok readFile($F) eq $s;

  my $C = gbBinaryStandardCompanionFileName($F);                                # Check companion file
  ok -e $C;
  ok gbBinaryStandardCompanionFileContent($C) eq $S;

  ok gbStandardCompanionFileContent($F) eq $S;                                  # Check companion file content

  ok !gbBinaryStandardRename($F);                                               # No rename required to standardize file name

  𝗴𝗯𝗕𝗶𝗻𝗮𝗿𝘆𝗦𝘁𝗮𝗻𝗱𝗮𝗿𝗱𝗗𝗲𝗹𝗲𝘁𝗲($F);                                                   # Delete file and its companion file
  ok !-e $F;
  ok !-e $C;

  clearFolder($_, 10) for $d, $D;
 }

This method can be imported via:

use Dita::GB::Standard qw(gbBinaryStandardDelete)

Index

1 gbBinaryStandardCompanionFileContent - Return the content of the "Companion File" given a file whose name complies with the binary GB Standard.

2 gbBinaryStandardCompanionFileName - Return the name of the companion file given a file whose name complies with the GB Standard.

3 gbBinaryStandardCopyFile - Copy a file to the specified $target folder renaming it to the GB Standard.

4 gbBinaryStandardCreateFile - Create a file in the specified $Folder whose name is the GB Standard name for the specified $content and return the file name, A "Companion File" can, optionally, be created with the specified $companionContent.

5 gbBinaryStandardDelete - Delete a file and its "Companion File" if there is one.

6 gbBinaryStandardFileName - Return the GB Standard file name given the content and extension of a proposed file.

7 gbBinaryStandardRename - Check whether a file needs to be renamed to match the GB Standard.

8 gbStandardCompanionFileContent - Return the content of the "Companion File" given a file whose name complies with the GB Standard.

9 gbStandardCompanionFileName - Return the name of the "Companion File" given a file whose name complies with the GB Standard.

10 gbStandardCopyFile - Copy a file to the specified $target folder renaming it to the GB Standard.

11 gbStandardCreateFile - Create a file in the specified $Folder whose name is the GB Standard name for the specified $content and return the file name, A "Companion File" can, optionally, be created with the specified $companionContent

12 gbStandardDelete - Delete a file and its companion file if there is one.

13 gbStandardFileName - Return the GB Standard file name given the content and extension of a proposed file.

14 gbStandardRename - Check whether a file needs to be renamed to match the GB Standard.

Exports

All of the following methods can be imported via:

use Dita::GB::Standard qw(:all);

Or individually via:

use Dita::GB::Standard qw(<method>);

1 gbBinaryStandardCompanionFileContent

2 gbBinaryStandardCompanionFileName

3 gbBinaryStandardCopyFile

4 gbBinaryStandardCreateFile

5 gbBinaryStandardDelete

6 gbBinaryStandardFileName

7 gbBinaryStandardRename

8 gbStandardCompanionFileContent

9 gbStandardCompanionFileName

10 gbStandardCopyFile

11 gbStandardCreateFile

12 gbStandardDelete

13 gbStandardFileName

14 gbStandardRename

Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:

sudo cpan install Dita::GB::Standard

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

To install Dita::GB::Standard, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Dita::GB::Standard

CPAN shell

perl -MCPAN -e shell
install Dita::GB::Standard

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Name

Synopsis

Benefits

Parallel Processing

File Flattening

Testing

Mixed Multiple Conversions

No Relative Paths in References

Relocating Dita References After Folder Restructuring

Similar Files Tend To Appear Close Together In Directory Listings.

Copying And Moving Files For Global Interoperability

Guidization For Content Management Systems

No need for authors to coordinate topic file names

Using Dita Tags To Describe Content

Cut And Paste

CSV files

Automatic File Versioning

Enhanced Command Line Processing

Locating Files by Their Original Names Or Other Meta-Data

Use with AWS Simple Storage Service

Companion File

Alternate File Names

Implementation

Binary vs Utf8

Documentation Copyright

Description

Make and manage utf8 files

gbStandardFileName($$%)

gbStandardCompanionFileName($)

gbStandardCompanionFileContent($)

gbStandardCreateFile($$$%)

gbStandardRename($%)

gbStandardCopyFile($%)

gbStandardDelete($)

Make and manage binary files

gbBinaryStandardFileName($$)

gbBinaryStandardCompanionFileName($)

gbBinaryStandardCompanionFileContent($)

gbBinaryStandardCreateFile($$$$)

gbBinaryStandardRename($)

gbBinaryStandardCopyFile($$)

gbBinaryStandardDelete($)

Index

Exports

Installation

Author

Copyright

Module Install Instructions