view release on metacpan or  search on metacpan

lib/Dita/GB/Standard.pm  view on Meta::CPAN

Thus clearing the production corpus by applying the L<GBStandard> 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.

`head3 Using Dita Tags To Describe Content

The L<GBStandard> encourages L<Dita> users to use meta data tags to describe
their documents so that content can be found by searching with L<grep> rather
than encoding file meta data in file names then searching for the required file
using L<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
L<commandLine>.

`head3 Cut And Paste

As there are no spaces in the files names created using the L<GBStandard> 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.

`head3 CSV files

Files named using the L<GBStandard> can be safely included in B<.csv> files
because they have no spaces in them!

`head3 Automatic File Versioning

Files named to the L<GBStandard> 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.

`head3 Enhanced Command Line Processing

As file names named with the L<GBStandard> do not have spaces in them (such as
L<zeroWidthSpace>) they work well on the L<commandLine> and with the many
L<commandLine> tools that are used to manipulate such files enhancing the
productivity leverage that L<commandLine> has always had versus L<GUI>
processing.

`head3 Locating Files by Their Original Names Or Other Meta-Data

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

To find such a file use L<grep> to find the L<Companion File> containing the
searched for content, paste that file name into the L<commandLine> after
entering any command such as B<ll> and then press B<.> followed by the L<tab>
key to have the L<shell> expand it to locate the L<GBStandard> file that
corresponds to the located L<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

`head3 Use with AWS Simple Storage Service

Viewing files held in L<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 B<G> part, the Human Readdable
Component, and press enter to see the possible candidates.

`head2 Companion File

Each file named using the L<GBStandard> may be accompanied by a
L<Companion File> that contains meta data describing the file, said data
formatted as a L<Perl> data structure.

The name of the L<Companion File> is obtained by removing the extension from the
file named using the L<GBStandard>.

As the content of the companion files is in plain text, such text is easy to
search using L<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),
  }

`head2 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 L<GBStandard> without disrupting the integrity of the L<GBStandard>.

For example: L<xref> produces B<Oxygen Project Files> which provide a virtual
hierarchical folder view of an otherwise flat folder.

`head2 Implementation

The L<GBStandard> has been implemented as a L<Perl> package at:

L<http://metacpan.org/pod/Dita::GB::Standard>

`head2 Binary vs Utf8

Files that are expected to contain data encoded with L<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 L<md5> value with the

lib/Dita/GB/Standard.pm  view on Meta::CPAN

Thus clearing the production corpus by applying the L<GB Standard|http://metacpan.org/pod/Dita::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.

=head3 Using Dita Tags To Describe Content

The L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> encourages L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html> users to use meta data tags to describe
their documents so that content can be found by searching with L<grep|https://en.wikipedia.org/wiki/Grep> rather
than encoding file meta data in file names then searching for the required file
using L<find|https://en.wikipedia.org/wiki/Find_(Unix)>.  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
L<command line|https://en.wikipedia.org/wiki/Command-line_interface>.

=head3 Cut And Paste

As there are no spaces in the files names created using the L<GB Standard|http://metacpan.org/pod/Dita::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.

=head3 CSV files

Files named using the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> can be safely included in B<.csv> files
because they have no spaces in them!

=head3 Automatic File Versioning

Files named to the L<GB Standard|http://metacpan.org/pod/Dita::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.

=head3 Enhanced Command Line Processing

As file names named with the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> do not have spaces in them (such as
L<zero width space|https://en.wikipedia.org/wiki/Zero-width_space>) they work well on the L<command line|https://en.wikipedia.org/wiki/Command-line_interface> and with the many
L<command line|https://en.wikipedia.org/wiki/Command-line_interface> tools that are used to manipulate such files enhancing the
productivity leverage that L<command line|https://en.wikipedia.org/wiki/Command-line_interface> has always had versus L<graphical user interface|https://en.wikipedia.org/wiki/Graphical_user_interface>
processing.

=head3 Locating Files by Their Original Names Or Other Meta-Data

Each file produced by the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> can have a L<Companion File> of the same
name but without an extension.  The L<Companion File> contains meta-data about the
file such as its original location etc. which can be searched by L<grep|https://en.wikipedia.org/wiki/Grep> or
similar.

To find such a file use L<grep|https://en.wikipedia.org/wiki/Grep> to find the L<Companion File> containing the
searched for content, paste that file name into the L<command line|https://en.wikipedia.org/wiki/Command-line_interface> after
entering any command such as B<ll> and then press B<.> followed by the L<tab|https://en.wikipedia.org/wiki/Tab_key>
key to have the L<shell|https://en.wikipedia.org/wiki/Shell_(computing)> expand it to locate the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> file that
corresponds to the located L<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

=head3 Use with AWS Simple Storage Service

Viewing files held in L<S3|https://s3.console.aws.amazon.com/s3/home> 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 B<G> part, the Human Readdable
Component, and press enter to see the possible candidates.

=head2 Companion File

Each file named using the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> may be accompanied by a
L<Companion File> that contains meta data describing the file, said data
formatted as a L<Perl|http://www.perl.org/> data structure.

The name of the L<Companion File> is obtained by removing the extension from the
file named using the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard>.

As the content of the companion files is in plain text, such text is easy to
search using L<grep|https://en.wikipedia.org/wiki/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),
  }

=head2 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 L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> without disrupting the integrity of the L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard>.

For example: L<Xref|https://metacpan.org/pod/Data::Edit::Xml::Xref> produces B<Oxygen Project Files> which provide a virtual
hierarchical folder view of an otherwise flat folder.

=head2 Implementation

The L<GB Standard|http://metacpan.org/pod/Dita::GB::Standard> has been implemented as a L<Perl|http://www.perl.org/> package at:

L<http://metacpan.org/pod/Dita::GB::Standard>

=head2 Binary vs Utf8

Files that are expected to contain data encoded with L<utf8|https://en.wikipedia.org/wiki/UTF-8> (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 L<md5 sum|https://en.wikipedia.org/wiki/MD5> value with the