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

Various documentation fixes and improvements #1

Merged
merged 6 commits into from Jul 1, 2016

Conversation

Projects
None yet
2 participants
@paultcochrane
Contributor

paultcochrane commented Jun 26, 2016

This PR fixes broken links, tries to make the text flow better, adds formatting for code-like textual elements and fixes POD errors. It is submitted in the hope that it is useful; any comments or questions you might have concerning the PR are most welcome! I've also tried to split the commits into small chunks so that they can be cherry-picked if so desired.

paultcochrane added some commits Jun 26, 2016

Make provenance of method name docs clearer
This adds a description to the link to the "metering primitives" page from
the Traffic Control project, which then makes the sentence flow better; a
link to the Traffic Control project has also been added, since other parts
of the documentation also point there and it seems to make sense to point to
the origin of the documentation.  The sentence flow has also been changed so
that it flows a bit better.
Point broken link to web.archive.org stored version
Unfortunately the assignments for cs143 at Harvard seem to require a login
to the Harvard website (the original link has been missing now for several
years).  The original text can now be accessed via the Internet Archive's
archived version; the version of the document linked here is the most recent
existing version.
Use a list for SEE ALSO links
This makes the list of links much easier to read in the POD and in the
generated Markdown used in the README.
Improve flow and add formatting to docs
This commit improves the sentence flow of the documentation as well as wraps
some code-like texutal elements in `C<>` formatting constructs so that
code-like things look like code in the documentation displayed in the README
on GitHub and in the HTML on e.g. MetaCPAN.
Fix internal link errors found by podchecker
The `state`, `until` and `get_token_count` methods merely needed to have
parens (and in the case of the `until` method, a dollar sign) added so that
the internal links were correctly resolved and no longer marked as errors by
`podchecker`.
@paultcochrane

This comment has been minimized.

Show comment
Hide comment
@paultcochrane

paultcochrane Jun 26, 2016

Contributor

By the way: I noticed that the README.md seemed to be automatically generated, hence I used Pod::Markdown to keep the README in sync with the updated POD. Changes to the README text are thus made parallel to the changes in the POD.

Contributor

paultcochrane commented Jun 26, 2016

By the way: I noticed that the README.md seemed to be automatically generated, hence I used Pod::Markdown to keep the README in sync with the updated POD. Changes to the README text are thus made parallel to the changes in the POD.

@kappa kappa merged commit d433f2a into kappa:master Jul 1, 2016

@kappa

This comment has been minimized.

Show comment
Hide comment
@kappa

kappa Jul 1, 2016

Owner

Thanks for the attention to details!

Owner

kappa commented Jul 1, 2016

Thanks for the attention to details!

@paultcochrane paultcochrane deleted the paultcochrane:pr/doc-fixes branch Jul 7, 2016

@paultcochrane

This comment has been minimized.

Show comment
Hide comment
@paultcochrane

paultcochrane Jul 7, 2016

Contributor

My pleasure! Hope the PRs helped!

Contributor

paultcochrane commented Jul 7, 2016

My pleasure! Hope the PRs helped!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment