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.

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.

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

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.

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 20190708.

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(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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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 = q(out/);
    my $D = q(out2/);
    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

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

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

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