[Refdb-cvs] CVS: refdb/scripts refdb-ms,NONE,1.1.2.1 document-dtd-entities,NONE,1.1.2.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/refdb/refdb/scripts
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv17094

Added Files:
      Tag: Release_0_9_5_stable
	refdb-ms document-dtd-entities 
Log Message:
moved over from makestyle module

--- NEW FILE ---
#!/usr/bin/perl

=head1 NAME

refdb-ms - RefDB MakeStyle, a bibliography style generator for RefDB

=head1 Summary

A utility to aid the generation of RefDB bibliography styles for RefDB <refdb.sourceforge.net>.

=head1 Requirements

One of the design goals for this utility was to minimise external dependencies.

=over

=item Refdb::Makestyle

A custom module containing methods and attributes used by this script.

Debian package: libperl-refdb-makestyle.

=back

=cut

use strict;
use RefDB::Makestyle;

$ENV{'CLUI_DIR'} = "OFF"; 

my $ui = UI->new();

die "Fatal errors encountered.\n" if not $ui->startup_checks();

=head1 The program

=head2 Style root

The root element of the style, C<CiteStyle>, is a data member of the user-interface (C<ui>) object.  All other elements of the style are children of the C<CiteStyle> element.

=cut

$ui->set_root( CiteStyle->new() );

=head2 Help system

There is a series of help screens.  See C<refdb-ms.pl> library for details.

=cut

print "RefDB MakeStyle -- generate bibliography styles for RefDB.\n";
$ui->help_system() if $ui->_input_confirm( "Do you require help?" );

=head2 Main entry loop

This is the main part of the program -- where the style itself is created.

It is short as most of the "work" is done by the C<refdb-ms.pl> library.

=cut

my ( $current_element , @choice , $child ) =
	( $ui->get_root()->get_last_incomplete() );
$current_element->add_attributes();
$current_element->enter_value();
while ( 1 ) {
	# Get working element
	$current_element = $ui->get_root()->get_last_incomplete();
	last if not defined $current_element;  # style is complete 
	# Add element attributes and content
	$current_element->add_attributes();
	$current_element->enter_value();
	# Provide feedback
	printf "\nProgress report:\n%s\n" , $ui->get_root()->show_progress();
	printf "Current element: %s\n" , $current_element->get_name();
	# Select next element/action
	@choice = $current_element->select_next_child();
	# Delete element if user selected that option
	if ( @choice[1] eq "[DELETE]" ) {
		$ui->delete_selected_element();
		next;
	}
	# If current element complete, skip next part
	next if not defined $choice[1];  # current element is complete
	printf "\n%s" , @choice[0];
	# Add newly selected element to style
	$child = $ui->create_element( @choice[1] );
	$current_element->add_child( $child );
}
print "\nThe style is now complete.\n";

=head2 Write output

The style is written to an C<xml> file.  If the default name, E<lt>I<stylename>-style.xmlE<gt>, already exists, another is created.

=cut

$ui->write_style();

=head2 Write summary

A summary of the style is written to an C<html> file.  It is meant as an aide memoire when entering references.

=cut

$ui->write_summary();

=head2 Upload style

The style can be uploaded to refdb.  If a pre-existing style of the same name exists it is backed up to file before the new style is added.

=cut

$ui->upload_style();

printf "\nStyle \"%s\" has been created.\nIt has been saved to file <%s>.\nA summary of the style has been written to file <%s>.\n\nRefDB Makestyle is finished.\n" , $ui->get_root()->get_style_name() , $ui->get_style_file() , $ui->get_summary_file();
exit 0;

=head1 AUTHOR

David Nebauer, david E<lt>atE<gt> nebauer E<lt>dotE<gt> org

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2004 by David Nebauer

Distributed under the same license and conditions as the C<Refdb> project E<lt>L<http://refdb.sourceforge.net/>E<gt>.

=cut

--- NEW FILE ---
#!/usr/bin/perl

=head1 document-dtd-entities

=head1 Summary

Extracts from C<refdb-ms.pl> certain data elements associated with citestylex DTD entities (i.e., elements and attributes).  This includes help and prompt text, default values and attribute enumerations.

Output is written to an html file.

=head1 Configuration

=head3 Find 'refdb-ms.pl'

This script must be able to find the perl library C<refdb-ms.pl>.  Either run this script in the same directory as C<refdb-ms.pl> or make sure C<refdb-ms.pl> is in a directory included in perl's @INC array.  To see the directories in the @INC array use the following command:

	perl -e "print join(\"\n\", @INC);"

=head3 Output filename

The output filename can be specified as an argument to C<document-dtd-entities>.

If one is not supplied the default filename C<dtd-entities.html> is used.

=head1 Running

When running this program an object of each entity class is created in order to be queried for its properties.  The object creation process usually requires no user input.  There are three exceptions: TYPE - Type_PubType, ROLE - Role_UserDef and ROLE - Role_Misc.  When these attributes are created you will be required to select a value from the enumeration list.  Select any value -- it does not matter.

=head1 Programmer notes

I have broken a general object-oriented programming "rule" in this utility.  I have directly accessed the attribute enumeration instead of using a "getter".  There is a good reason: for three attributes (TYPE - Type_PubType, ROLE - Role_UserDef and ROLE - Role_Misc) the get->enumeration method returns an incomplete list.  It omits those enumeration values already selected by existing attributes.

=cut

use strict;

require "refdb-ms.pl";

# Print informational message
print "In the process of extracting entity help each entity is created once.\nSome entities require user interaction.\nIt does not matter what values you enter/select when this occurs.\n-----------------------------------------\n";

# Get output filename
my $file = shift;
$file = ( $file ) ? $file : "dtd-entities.html";

# Set attribute and element lists
my @attributes = qw/ Type_PubType Type_PageRange Style Role_AuthorList Role_PubDate Role_Title Role_UserDef Role_Misc DisplayAuthor MaxAuthor UpperCase InitialStyle NameOrder Sequence Format YearFormat MonthFormat PadLeadingZero DayFormat Case AlternateText DefaultText Punctuation BiblioSequence InTextSequence Threelet_Jan Threelet_Feb Threelet_Mar Threelet_Apr Threelet_May Threelet_Jun Threelet_Jul Threelet_Aug Threelet_Sep Threelet_Oct Threelet_Nov Threelet_Dec Abbrev_Jan Abbrev_Feb Abbrev_Mar Abbrev_Apr Abbrev_May Abbrev_Jun Abbrev_Jul Abbrev_Aug Abbrev_Sep Abbrev_Oct Abbrev_Nov Abbrev_Dec Full_Jan Full_Feb Full_Mar Full_Apr Full_May Full_Jun Full_Jul Full_Aug Full_Sep Full_Oct Full_Nov Full_Dec /;

my @elements = qw/ StyleSet CiteStyle StyleName RefStyle PubType RefNumber Preceeding Following AuthorList AbbreviateFirst AbbreviateSubseq Aempty Asame AuthorSeps TwoSeps ThreeSeps ThreeSepsEach ThreeSepsLast AuthorNames NameFirst NameOther Text TextSingle TextMultiple PubDate FirstSep SecondSep Title JournalName Volume Issue Pages SinglePage PageRange RangeSeparator Publisher PubPlace Serial Address Url UserDef Misc Notes Abstract Separator CitStyle CitSeparator BiblioTitle InTextDef AuthorOnly YearOnly Months Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec /;

# Start output file
my $output = "<html>\n<head><title>'citestylex' DTD Entity Documentation</title></head>\n<body>\n<h1><i>citestylex</i> DTD Entity Documentation</h1>\n<h4>Source</h4>\n<p>Extracted from &lt;<tt>refdb-ms.pl</tt>&gt;.</p>\n";

# Extract attribute help
$output .= "<h2>Attributes</h2>\n";
foreach ( @attributes ) {
	my ( $att , $enum_list ) = ( $_->new() , "" );
	my ( $att_name , $att_class ) = ( $att->get_name() , $att->get_classname() );
	$output .= sprintf "<h3>%s (%s)</h3>\n" , $att_name , $att_class;
	$output .= sprintf "<h4>Prompt</h4>\n<p>%s</p>\n" , $att->get_prompt();
	if ( defined( $att->{enumeration} ) ) {
		 foreach ( sort @{ $att->{enumeration} } ) { $enum_list .= $_ . " | "; }
	 }
	if ( $enum_list =~ /|/ ) {
		$enum_list =~ /^(.*) \| $/;
		$enum_list = $1;
	}
	$enum_list = $enum_list ? $enum_list : "<i>[None]</i>";
	$output .= sprintf "<h4>Enumeration</h4>\n<p>%s</p>\n" , $enum_list;
	$output .= sprintf "<h4>Default</h4>\n<p>%s</p>\n" , $att->get_default();
}

# Extract element help
$output .= "<hr><br>\n<h2>Elements</h2>\n";
foreach ( @elements ) {
	my $element = $_->new();
	$output .= sprintf "<h3>%s</h3>\n" , $element->get_name();
	$output .= sprintf "<h4>Prompt</h4>\n<p>%s</p>\n" , $element->get_prompt();
	if ( $element->get_suggestion() ) {
		$output .= sprintf( "<h4>Suggested value</h4>\n<p>\"%s\"</p>\n" , 
		                    $element->get_suggestion()
						  );
	}
	$output .= sprintf "<h4>Help</h4>\n<p>%s</p>\n" , $element->get_help();
}

# Finish output
$output .= "<hr>\n</body>\n</html>";

# Print to file
open FILE , "> $file";
print FILE $output;
close FILE;

# Print informational message
printf "-----------------------------------------\nOutput written to \"%s\".\n" , $file;