Skip to content

Commit 631f8b6

Browse files
vanderleevanderlee
committed
Improved docs
1 parent eed6399 commit 631f8b6

File tree

5 files changed

+191
-45
lines changed

5 files changed

+191
-45
lines changed

‎README.md

+86-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Version 1.4.2
44

55
[![Build Status](https://travis-ci.org/vanderlee/phpSyllable.svg)](https://travis-ci.org/vanderlee/phpSyllable)
66

7-
Copyright © 2011-2015 Martijn van der Lee.
7+
Copyright © 2011-2016 Martijn van der Lee.
88
MIT Open Source license applies.
99

1010
Introduction
@@ -23,8 +23,93 @@ Language sources: http://tug.org/tex-hyphen/#languages
2323

2424
Supports PHP 5.2 and up, so you can use it on older servers.
2525

26+
Quick start
27+
-----------
28+
Just include phpSyllable in your project, set up the autoloader to the classes
29+
directory and instantiate yourself a Sylllable class.
30+
31+
$syllable = new Syllable('en-us');
32+
echo $syllable->hyphenateText('Provide a plethora of paragraphs');
33+
34+
`Syllable` class reference
35+
--------------------------
36+
The following is an incomplete list, containing only the most common methods.
37+
For a complete documentation of all classes, read the generated [PHPDoc](doc).
38+
39+
### public static __construct( $language = 'en', $hyphen = null )
40+
Create a new Syllable class, with defaults
41+
42+
### public static setCacheDir( $dir )
43+
Set the directory where compiled language files may be stored.
44+
Default to the `cache` subdirectory of the current directory.
45+
46+
### public static setLanguageDir( $dir )
47+
Set the directory where language source files can be found.
48+
Default to the `languages` subdirectory of the current directory.
49+
50+
### public setLanguage( $language )
51+
Set the language whose rules will be used for hyphenation.
52+
53+
### public setHyphen( Mixed $hyphen )
54+
Set the hyphen text or object to use as a hyphen marker.
55+
56+
### public array splitWord( $word )
57+
Split a single word on where the hyphenation would go.
58+
59+
### public array splitText( $text )
60+
Split a text on where the hyphenation would go.
61+
62+
### public string hyphenateWord( $word )
63+
Hyphenate a single word.
64+
65+
### public string hyphenateText( $text )
66+
Hyphenate all words in the plain text.
67+
68+
### public string hyphenateHtml( $html )
69+
Hyphenate all readable text in the HTML, excluding HTML tags and attributes.
70+
71+
### public array histogramText( $text )
72+
Count the number of syllables in the text and return a map with
73+
syllable count as key and number of words for that syllable count as
74+
the value.
75+
76+
### public integer countWordsText( $text )
77+
Count the number of words in the text.
78+
79+
### public integer countPolysyllablesText( $text )
80+
Count the number of polysyllables in the text.
81+
82+
Example
83+
-------
84+
See the included [demo.php](demo.php) file for a working example.
85+
86+
// Setup the autoloader (if needed)
87+
require_once dirname(__FILE__) . '/classes/autoloader.php';
88+
89+
// Create a new instance for the language
90+
$syllable = new Syllable('en-us');
91+
92+
// Set the directory where the .tex files are stored
93+
$syllable->getSource()->setPath(__DIR__ . '/languages');
94+
95+
// Set the directory where Syllable can store cache files
96+
$syllable->getCache()->setPath(__DIR__ . '/cache');
97+
98+
// Set the hyphen style. In this case, the ­ HTML entity
99+
// for HTML (falls back to '-' for text)
100+
$syllable->setHyphen(new Syllable_Hyphen_Soft);
101+
102+
// Set the treshold (sensitivity)
103+
$syllable->setTreshold(Syllable::TRESHOLD_MOST);
104+
105+
// Output hyphenated text
106+
echo $syllable->hyphenateText('Provide your own paragraphs...');
107+
26108
Changes
27109
-------
110+
1.4.3
111+
- Improved documentation
112+
28113
1.4.2
29114
- Updated spanish language files.
30115
- Initial PHPDoc.

‎TODO renamed to ‎TODO.md

File renamed without changes.

‎classes/Syllable.php

+73-7
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ class Syllable {
4848
private static $cache_dir = null;
4949
private static $language_dir = null;
5050

51+
/**
52+
* Create a new Syllable class, with defaults
53+
* @param string $language
54+
* @param string|Syllable_Hyphen_Interface $hyphen
55+
*/
5156
public function __construct($language = 'en', $hyphen = null) {
5257
if (!self::$cache_dir) {
5358
self::$cache_dir = __DIR__.'/cache';
@@ -67,21 +72,35 @@ public function __construct($language = 'en', $hyphen = null) {
6772
$this->setHyphen($hyphen? $hyphen : new Syllable_Hyphen_Soft());
6873
}
6974

75+
/**
76+
* Set the directory where compiled language files may be stored.
77+
* Default to the `cache` subdirectory of the current directory.
78+
* @param string $dir
79+
*/
7080
public static function setCacheDir($dir) {
7181
self::$cache_dir = $dir;
7282
}
73-
83+
84+
/**
85+
* Set the directory where language source files can be found.
86+
* Default to the `languages` subdirectory of the current directory.
87+
* @param string $dir
88+
*/
7489
public static function setLanguageDir($dir) {
7590
self::$language_dir = $dir;
7691
}
77-
92+
93+
/**
94+
* Set the language whose rules will be used for hyphenation.
95+
* @param string $language
96+
*/
7897
public function setLanguage($language) {
7998
$this->language = $language;
8099
$this->setSource(new Syllable_Source_File($language, self::$language_dir));
81100
}
82101

83102
/**
84-
* Set the hyphen to use when hyphenating text
103+
* Set the hyphen text or object to use as a hyphen marker.
85104
* @param Mixed $hyphen either a Syllable_Hyphen_Interface or a string, which is turned into a Syllable_Hyphen_Text
86105
*/
87106
public function setHyphen($hyphen) {
@@ -91,7 +110,7 @@ public function setHyphen($hyphen) {
91110
}
92111

93112
/**
94-
*
113+
* Get the current hyphen object.
95114
* @return Syllable_Hyphen_Interface hyphen
96115
*/
97116
public function getHyphen() {
@@ -147,6 +166,11 @@ public function getSource() {
147166
return $this->Source;
148167
}
149168

169+
/**
170+
* Split a single word on where the hyphenation would go.
171+
* @param string $text
172+
* @return array
173+
*/
150174
public function splitWord($word) {
151175
mb_internal_encoding('UTF-8'); //@todo upwards?
152176
mb_regex_encoding('UTF-8'); //@todo upwards?
@@ -156,6 +180,11 @@ public function splitWord($word) {
156180
return $this->parseWord($word);
157181
}
158182

183+
/**
184+
* Split a text on where the hyphenation would go.
185+
* @param string $text
186+
* @return array
187+
*/
159188
public function splitText($text) {
160189
mb_internal_encoding('UTF-8'); //@todo upwards?
161190
mb_regex_encoding('UTF-8'); //@todo upwards?
@@ -195,16 +224,32 @@ public function splitText($text) {
195224
return $parts;
196225
}
197226

227+
/**
228+
* Hyphenate a single word.
229+
* @param string $html
230+
* @return string
231+
*/
198232
public function hyphenateWord($word) {
199233
$parts = $this->splitWord($word);
200234
return $this->Hyphen->joinText($parts);
201235
}
202236

237+
/**
238+
* Hyphenate all words in the plain text.
239+
* @param string $html
240+
* @return string
241+
*/
203242
public function hyphenateText($text) {
204243
$parts = $this->splitText($text);
205244
return $this->Hyphen->joinText($parts);
206245
}
207246

247+
/**
248+
* Hyphenate all readable text in the HTML, excluding HTML tags and
249+
* attributes.
250+
* @param string $html
251+
* @return string
252+
*/
208253
public function hyphenateHtml($html) {
209254
$dom = new DOMDocument();
210255
$dom->resolveExternals = true;
@@ -215,6 +260,10 @@ public function hyphenateHtml($html) {
215260
return $dom->saveHTML();
216261
}
217262

263+
/**
264+
* Add hyphenation to the DOM nodes.
265+
* @param DOMNode $node
266+
*/
218267
private function hyphenateHtmlDom(DOMNode $node) {
219268
if ($node->hasChildNodes()) {
220269
foreach ($node->childNodes as $child) {
@@ -227,7 +276,14 @@ private function hyphenateHtmlDom(DOMNode $node) {
227276
$this->Hyphen->joinHtmlDom($parts, $node);
228277
}
229278
}
230-
279+
280+
/**
281+
* Count the number of syllables in the text and return a map with
282+
* syllable count as key and number of words for that syllable count as
283+
* the value.
284+
* @param string $text
285+
* @return array
286+
*/
231287
public function histogramText($text) {
232288
mb_internal_encoding('UTF-8'); //@todo upwards?
233289
mb_regex_encoding('UTF-8'); //@todo upwards?
@@ -248,7 +304,12 @@ public function histogramText($text) {
248304

249305
return $counts;
250306
}
251-
307+
308+
/**
309+
* Count the number of words in the text.
310+
* @param string $text
311+
* @return int
312+
*/
252313
public function countWordsText($text) {
253314
mb_internal_encoding('UTF-8'); //@todo upwards?
254315
mb_regex_encoding('UTF-8'); //@todo upwards?
@@ -264,7 +325,12 @@ public function countWordsText($text) {
264325

265326
return $count;
266327
}
267-
328+
329+
/**
330+
* Count the number of polysyllables in the text.
331+
* @param string $text
332+
* @return int
333+
*/
268334
public function countPolysyllablesText($text) {
269335
mb_internal_encoding('UTF-8'); //@todo upwards?
270336
mb_regex_encoding('UTF-8'); //@todo upwards?

‎index.php renamed to ‎demo.php

File renamed without changes.

‎index.html

+32-37
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
<style>
2020
body {
2121
font-family: "Segoe UI", Verdana, Helvetica, Arial, sans-serif;
22-
font-size: 11px;
22+
font-size: 13px;
2323
padding: 3em 8em 1em 4em;
2424
}
2525

@@ -51,17 +51,38 @@
5151
text-align: justify;
5252
}
5353

54-
h1,
55-
h2 {
56-
background: black;
57-
color: white;
58-
padding: .2em .4em;
54+
p {
55+
margin: .4em 0 1.2em .8em;
56+
}
57+
58+
h1, h2, h3, h4 {
59+
margin-top: 1.6em;
60+
margin-bottom: .4em;
61+
}
62+
63+
h1, h2 {
64+
border-top-left-radius: 1em;
65+
border-top-right-radius: 2em;
66+
padding: .2em .4em .2em .8em;
67+
background: #34495e;
68+
color: white;
5969
}
6070
h1 {
61-
margin-top: 1em;
71+
margin-top: 2em;
6272
}
6373
h2 {
64-
background: gray;
74+
background: #95a5a6;
75+
}
76+
h3 {
77+
border-bottom: thin solid #95a5a6;
78+
margin-left: .4em;
79+
}
80+
h4 {
81+
margin: .4em 0 .2em 0;
82+
}
83+
84+
ul, ol {
85+
padding-left: 2em;
6586
}
6687

6788
hr {
@@ -153,6 +174,8 @@
153174
});
154175
}
155176

177+
$('.year').text((new Date).getFullYear());
178+
156179
// extract html fragments
157180
$('div.prettyprint, span.prettyprint').each(function() {
158181
visualizeElement(this, 'HTML');
@@ -193,38 +216,10 @@
193216

194217
<div id="book">
195218
<div id="readme"></div>
196-
197-
<h1>Examples</h1>
198-
<div id="examples" class="chapter">
199-
See the included index.php file for a working example.
200-
<script class="prettyprint" type="text/php">
201-
// Setup the autoloader (if needed)
202-
require_once dirname(__FILE__) . '/classes/autoloader.php';
203-
204-
// Create a new instance for the language
205-
$syllable = new Syllable('en-us');
206-
207-
// Set the directory where the .tex files are stored
208-
$syllable->getSource()->setPath(dirname(__FILE__).'/languages');
209-
210-
// Set the directory where Syllable can store cache files
211-
$syllable->getCache()->setPath(dirname(__FILE__).'/cache');
212-
213-
// Set the hyphen style. In this case, the &shy; HTML entity
214-
// for HTML (falls back to '-' for text)
215-
$syllable->setHyphen(new Syllable_Hyphen_Soft);
216-
217-
// Set the treshold (sensitivity)
218-
$syllable->setTreshold(Syllable::TRESHOLD_MOST);
219-
220-
// Output hyphenated text
221-
echo $syllable->hyphenateText('Provide your own paragraphs...');
222-
</script>
223-
</div>
224219
</div>
225220

226221
<div id="footer">
227-
Copyright &copy; 2010-2015 Martijn van der Lee. MIT Open Source license applies.
222+
Copyright &copy; <span class="year">2015</span> Martijn van der Lee. MIT Open Source license applies.
228223
</div>
229224
</body>
230225
</html>

0 commit comments

Comments
 (0)