Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation cleanup #10

Merged
merged 9 commits into from Aug 1, 2015
Merged

Documentation cleanup #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7a6eee7
Add =pod mark
andyjack Aug 1, 2015
4aa996a
Strip trailing spaces
andyjack Aug 1, 2015
49db520
Remove unneeded newlines in pod
andyjack Aug 1, 2015
b32ac5d
Consistent capitalization of XML and Kate
andyjack Aug 1, 2015
b7724a1
Add author test for pod in Kate.pm
andyjack Aug 1, 2015
971619a
Use direct object notation in Synopsis
andyjack Aug 1, 2015
71128df
Tidy perl in Synopsis; make more concise
andyjack Aug 1, 2015
024894c
More perltidying
andyjack Aug 1, 2015
a40fc2f
Reformat and spelling correction
andyjack Aug 1, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
254 changes: 139 additions & 115 deletions lib/Syntax/Highlight/Engine/Kate.pm
View file
Open in desktop
Expand Up @@ -677,112 +677,86 @@ sub syntaxes {

__END__

=pod

=head1 NAME

Syntax::Highlight::Engine::Kate - a port to Perl of the syntax highlight engine of the Kate texteditor.
Syntax::Highlight::Engine::Kate - a port to Perl of the syntax highlight engine of the Kate text editor.

=head1 SYNOPSIS

#if you want to create a compiled executable, you may want to do this:
use Syntax::Highlight::Engine::Kate::All;

use Syntax::Highlight::Engine::Kate;
my $hl = new Syntax::Highlight::Engine::Kate(
language => 'Perl',
substitutions => {
"<" => "&lt;",
">" => "&gt;",
"&" => "&amp;",
" " => "&nbsp;",
"\t" => "&nbsp;&nbsp;&nbsp;",
"\n" => "<BR>\n",
},
format_table => {
Alert => ["<font color=\"#0000ff\">", "</font>"],
BaseN => ["<font color=\"#007f00\">", "</font>"],
BString => ["<font color=\"#c9a7ff\">", "</font>"],
Char => ["<font color=\"#ff00ff\">", "</font>"],
Comment => ["<font color=\"#7f7f7f\"><i>", "</i></font>"],
DataType => ["<font color=\"#0000ff\">", "</font>"],
DecVal => ["<font color=\"#00007f\">", "</font>"],
Error => ["<font color=\"#ff0000\"><b><i>", "</i></b></font>"],
Float => ["<font color=\"#00007f\">", "</font>"],
Function => ["<font color=\"#007f00\">", "</font>"],
IString => ["<font color=\"#ff0000\">", ""],
Keyword => ["<b>", "</b>"],
Normal => ["", ""],
Operator => ["<font color=\"#ffa500\">", "</font>"],
Others => ["<font color=\"#b03060\">", "</font>"],
RegionMarker => ["<font color=\"#96b9ff\"><i>", "</i></font>"],
Reserved => ["<font color=\"#9b30ff\"><b>", "</b></font>"],
String => ["<font color=\"#ff0000\">", "</font>"],
Variable => ["<font color=\"#0000ff\"><b>", "</b></font>"],
Warning => ["<font color=\"#0000ff\"><b><i>", "</b></i></font>"],
},
my $hl = Syntax::Highlight::Engine::Kate->new(
language => 'Perl',
substitutions => {
"<" => "&lt;",
">" => "&gt;",
"&" => "&amp;",
" " => "&nbsp;",
"\t" => "&nbsp;&nbsp;&nbsp;",
"\n" => "<BR>\n",
},
format_table => {
Alert => [ "<font color=\"#0000ff\">", "</font>" ],
BaseN => [ "<font color=\"#007f00\">", "</font>" ],
BString => [ "<font color=\"#c9a7ff\">", "</font>" ],
Char => [ "<font color=\"#ff00ff\">", "</font>" ],
Comment => [ "<font color=\"#7f7f7f\"><i>", "</i></font>" ],
DataType => [ "<font color=\"#0000ff\">", "</font>" ],
DecVal => [ "<font color=\"#00007f\">", "</font>" ],
Error => [ "<font color=\"#ff0000\"><b><i>", "</i></b></font>" ],
Float => [ "<font color=\"#00007f\">", "</font>" ],
Function => [ "<font color=\"#007f00\">", "</font>" ],
IString => [ "<font color=\"#ff0000\">", "" ],
Keyword => [ "<b>", "</b>" ],
Normal => [ "", "" ],
Operator => [ "<font color=\"#ffa500\">", "</font>" ],
Others => [ "<font color=\"#b03060\">", "</font>" ],
RegionMarker => [ "<font color=\"#96b9ff\"><i>", "</i></font>" ],
Reserved => [ "<font color=\"#9b30ff\"><b>", "</b></font>" ],
String => [ "<font color=\"#ff0000\">", "</font>" ],
Variable => [ "<font color=\"#0000ff\"><b>", "</b></font>" ],
Warning => [ "<font color=\"#0000ff\"><b><i>", "</b></i></font>" ],
},
);

#or

my $hl = new Syntax::Highlight::Engine::Kate::Perl(
substitutions => {
"<" => "&lt;",
">" => "&gt;",
"&" => "&amp;",
" " => "&nbsp;",
"\t" => "&nbsp;&nbsp;&nbsp;",
"\n" => "<BR>\n",
},
format_table => {
Alert => ["<font color=\"#0000ff\">", "</font>"],
BaseN => ["<font color=\"#007f00\">", "</font>"],
BString => ["<font color=\"#c9a7ff\">", "</font>"],
Char => ["<font color=\"#ff00ff\">", "</font>"],
Comment => ["<font color=\"#7f7f7f\"><i>", "</i></font>"],
DataType => ["<font color=\"#0000ff\">", "</font>"],
DecVal => ["<font color=\"#00007f\">", "</font>"],
Error => ["<font color=\"#ff0000\"><b><i>", "</i></b></font>"],
Float => ["<font color=\"#00007f\">", "</font>"],
Function => ["<font color=\"#007f00\">", "</font>"],
IString => ["<font color=\"#ff0000\">", ""],
Keyword => ["<b>", "</b>"],
Normal => ["", ""],
Operator => ["<font color=\"#ffa500\">", "</font>"],
Others => ["<font color=\"#b03060\">", "</font>"],
RegionMarker => ["<font color=\"#96b9ff\"><i>", "</i></font>"],
Reserved => ["<font color=\"#9b30ff\"><b>", "</b></font>"],
String => ["<font color=\"#ff0000\">", "</font>"],
Variable => ["<font color=\"#0000ff\"><b>", "</b></font>"],
Warning => ["<font color=\"#0000ff\"><b><i>", "</b></i></font>"],
},

my $hl = Syntax::Highlight::Engine::Kate::Perl->new(
substitutions => {
# ...
},
format_table => {
# ...
},
);



print "<html>\n<head>\n</head>\n<body>\n";
while (my $in = <>) {
print $hl->highlightText($in);
while ( my $in = <> ) {
print $hl->highlightText($in);
}
print "</body>\n</html>\n";

=head1 DESCRIPTION

Syntax::Highlight::Engine::Kate is a port to perl of the syntax highlight engine of the
Syntax::Highlight::Engine::Kate is a port to Perl of the syntax highlight engine of the
Kate text editor.

The language xml files of kate have been rewritten to perl modules using a script. These modules
The language XML files of Kate have been rewritten to Perl modules using a script. These modules
function as plugins to this module.

Syntax::Highlight::Engine::Kate inherits Syntax::Highlight::Engine::Kate::Template.
Syntax::Highlight::Engine::Kate inherits L<Syntax::Highlight::Engine::Kate::Template>.

=head1 OPTIONS

=over 4

=item B<language>

Specify the language you want highlighted.
look in the B<PLUGINS> section for supported languages.


Specify the language you want highlighted. Look in the B<PLUGINS> section for supported languages.

=item B<plugins>

Expand All @@ -798,12 +772,10 @@ If you created your own language plugins you may specify a list of them with thi
This option must be specified if the B<highlightText> method needs to do anything useful for you.
All mentioned keys in the synopsis must be specified.


=item B<substitutions>

With this option you can specify additional formatting options.


=back

=head1 METHODS
Expand All @@ -812,31 +784,31 @@ With this option you can specify additional formatting options.

=item B<extensions>

returns a reference to the extensions hash,
Returns a reference to the extensions hash.

=item B<language>(I<?$language?>)

Sets and returns the current language that is highlighted. when setting the language a reset is also done.
Sets and returns the current language that is highlighted. When setting the language a reset is also done.

=item B<languageAutoSet>(I<$filename>);
=item B<languageAutoSet>(I<$filename>)

Suggests language name for the fiven file B<$filename>
Suggests language name for the given file B<$filename>.

=item B<languageList>

returns a list of languages for which plugins have been defined.
Returns a list of languages for which plugins have been defined.

=item B<languagePlug>(I<$language>, I<?$insensitive?>);
=item B<languagePlug>(I<$language>, I<?$insensitive?>)

Returns the module name of the plugin for B<$language>.

If B<$insensitive> is set it will also try to match names ignoring case and return the correct module name of the plugin.

e.g. $highlighter->languagePlug('HtMl', 1); will return 'HTML'.
e.g. C<< $highlighter->languagePlug('HtMl', 1); >> will return C<< HTML >>.

=item B<languagePropose>(I<$filename>);
=item B<languagePropose>(I<$filename>)

Suggests language name for the fiven file B<$filename>
Suggests language name for the given file B<$filename>.

=item B<sections>

Expand All @@ -846,23 +818,71 @@ Returns a reference to the sections hash.

=head1 ATTRIBUTES

In the kate XML syntax files you find under the section B<<itemDatas>> entries like
<itemData name="Unknown Property" defStyleNum="dsError" italic="1"/>. Kate is an editor
so it is ok to have definitions for forground and background colors and so on. However,
since this Module is supposed to be a more universal highlight engine, the attributes need
In the Kate XML syntax files you find under the section B<<itemDatas>> entries like
C<< <itemData name="Unknown Property" defStyleNum="dsError" italic="1"/> >>. Kate is an editor
so it is ok to have definitions for foreground and background colors and so on. However,
since this module is supposed to be a more universal highlight engine, the attributes need
to be fully abstract. In which case, Kate does not have enough default attributes defined
to fullfill all needs. Kate defines the following standard attributes: B<dsNormal>, B<dsKeyword>,
B<dsDataType>, B<dsDecVal>, B<dsBaseN>, B<dsFloat>, B<dsChar>, B<dsString>, B<dsComment>, B<dsOthers>,
B<dsAlert>, B<dsFunction>, B<dsRegionMarker>, B<dsError>. This module leaves out the "ds" part and uses
following additional attributes: B<BString>, B<IString>, B<Operator>, B<Reserved>, B<Variable>. I have
modified the XML files so that each highlight mode would get it's own attribute. In quite a few cases
still not enough attributes were defined. So in some languages different modes have the same attribute.
to fulfill all needs. Kate defines the following standard attributes:

=over 4

=item * B<dsNormal>

=item * B<dsKeyword>

=item * B<dsDataType>

=item * B<dsDecVal>

=item * B<dsBaseN>

=item * B<dsFloat>

=item * B<dsChar>

=item * B<dsString>

=item * B<dsComment>

=item * B<dsOthers>

=item * B<dsAlert>

=item * B<dsFunction>

=item * B<dsRegionMarker>

=item * B<dsError>

=back

This module leaves out the B<<ds>> part and uses following additional attributes:

=over 4

=item * B<BString>

=item * B<IString>

=item * B<Operator>

=item * B<Reserved>

=item * B<Variable>

=back

I have modified the XML files so that each highlight mode would get its own
attribute. In quite a few cases still not enough attributes were defined. So in
some languages different modes have the same attribute.

=head1 PLUGINS

Below an overview of existing plugins. All have been tested on use and can be created. The ones for which no samplefile
is available are marked. Those marked OK have highlighted the testfile without appearant mistakes. This does
not mean that all bugs are shaken out.
Below is an overview of existing plugins. All have been tested on use and can be
created. The ones for which no sample file is available are marked. Those marked
OK have highlighted the test file without apparent mistakes. This does not mean
that all bugs are shaken out.

LANGUAGE MODULE COMMENT
******** ****** ******
Expand Down Expand Up @@ -993,15 +1013,14 @@ not mean that all bugs are shaken out.
xslt Xslt No sample file
yacas Yacas No sample file


=head1 BUGS

Float is detected differently than in the Kate editor.

The regular expression engine of the Kate editor, qregexp, appears to be more tolerant to mistakes
in regular expressions than perl. This might lead to error messages and differences in behaviour.
in regular expressions than Perl. This might lead to error messages and differences in behaviour.
Most of the problems were sorted out while developing, because error messages appeared. For as far
as differences in behaviour is concerned, testing is the only way to find out, so i hope the users
as differences in behaviour is concerned, testing is the only way to find out, so I hope the users
out there will be able to tell me more.

This module is mimicking the behaviour of the syntax highlight engine of the Kate editor. If you find
Expand All @@ -1010,18 +1029,18 @@ likely to be found there.

=head1 TO DO

Rebuild the scripts i am using to generate the modules from xml files so they are more pro-actively tracking
flaws in the build of the xml files like missing lists. Also regular expressions in the xml can be tested better
before used in plugins.
Rebuild the scripts I am using to generate the modules from XML files so they are more pro-actively tracking
flaws in the build of the XML files like missing lists. Also regular expressions in the XML can be tested better
before they are used in plugins.

Refine the testmethods in Syntax::Highlight::Engine::Kate::Template, so that choices for casesensitivity,
Refine the test methods in L<Syntax::Highlight::Engine::Kate::Template>, so that choices for case sensitivity,
dynamic behaviour and lookahead can be determined at generate time of the plugin, might increase throughput.

Implement codefolding.
Implement code folding.

=head1 ACKNOWLEDGEMENTS

All the people who wrote Kate and the syntax highlight xml files.
All the people who wrote Kate and the syntax highlight XML files.

=head1 AUTHOR AND COPYRIGHT

Expand All @@ -1031,12 +1050,17 @@ Hans Jeuken < haje at toneel dot demon dot nl >

Copyright (c) 2006 by Hans Jeuken, all rights reserved.

You may freely distribute and/or modify this module under the same terms
as Perl itself.
You may freely distribute and/or modify this module under the same terms
as Perl itself.

=head1 SEE ALSO

Syntax::Highlight::Engine::Kate::Template http:://www.kate-editor.org
=over 4

=cut
=item * L<Syntax::Highlight::Engine::Kate::Template>

=item * L<http://www.kate-editor.org>

=back

=cut
11 changes: 11 additions & 0 deletions xt/author/pod.t
View file
Open in desktop
@@ -0,0 +1,11 @@
#!/usr/bin/env perl

use strict;
use warnings;

use Test::More;
eval 'use Test::Pod 1.00';
plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@;

pod_file_ok('lib/Syntax/Highlight/Engine/Kate.pm');
done_testing();