Repository navigation
Add an AtomPub reference guide - #211
Merged
snoopdave merged 3 commits intoOct 10, 2026
Merged
Conversation
docs/roller-atompub-guide.adoc documents Roller's whole AtomPub interface: enabling and limits, BASIC and OAuth authentication, the service document, and the entries, media, category, template and comment resources (URIs, permissions, elements, status codes), with a curl session and an error table. It is built to PDF and shipped with the other guides. - docs/atompub/examples: XML examples included by the guide. Response examples are generated from AtomWriter by AtomPubDocExamplesTest, which fails when they no longer match (-Datompub.docs.update=true rewrites them). Request examples are hand-written and must parse. - docs/atompub/roller-atompub.rnc: RELAX NG grammar for the roller:* and thr:in-reply-to elements; the test validates every example against it and against the RFC 4287/5023 grammars. - Move the Jing helper into RelaxNgValidator for both schema tests.
snoopdave
added a commit
that referenced
this pull request
Oct 10, 2026
* Manage templates, categories and comments over AtomPub
Add three AtomPub collections to each weblog's workspace:
- Templates (/{handle}/templates): create, read, update and delete a
custom theme's templates, with the standard rendition as atom:content
and the mobile rendition as roller:rendition. Weblog administrators
only, and only while the weblog uses a custom theme and the site
allows custom themes. An empty mobile rendition removes it.
- Categories (/{handle}/categories): create, read, update and delete.
A category in use is removed only with ?moveTo={id}. The entries
collection lists categories inline and also references a new RFC 5023
category document at /{handle}/categories.atomcat.
- Comments (/{handle}/comments): moderation only. List (filter by status
or entry), change roller:status, delete. thr:in-reply-to (RFC 4685)
links to the weblog entry.
Move the template rules from the Templates and TemplateEdit pages into
WeblogTemplateEditor so the UI and AtomPub enforce the same rules, and
add WeblogManager.removeTemplateRendition() for mobile renditions.
* Address PR #209 review findings
- Refuse to delete a weblog's last category (409), as the Categories
page does.
- Make isWeblogCategoryInUse() null-safe for weblogs without a default
category.
- Test that deleting the default category with moveTo hands the default
over, and that the servlet serves the category document.
* Apply the category editor's field rules to AtomPub
- roller:image must be an http or https URL, as on the Categories page,
which now uses the same check. The category wrapper gives templates
only such URLs.
- Category names and descriptions, and template names, links and
descriptions, are limited to 255 characters, as in the editors.
- Test that AtomPub tags use the shared tag character rules.
* Add an AtomPub reference guide (#211)
* Add an AtomPub reference guide
docs/roller-atompub-guide.adoc documents Roller's whole AtomPub
interface: enabling and limits, BASIC and OAuth authentication, the
service document, and the entries, media, category, template and comment
resources (URIs, permissions, elements, status codes), with a curl
session and an error table. It is built to PDF and shipped with the
other guides.
- docs/atompub/examples: XML examples included by the guide. Response
examples are generated from AtomWriter by AtomPubDocExamplesTest, which
fails when they no longer match (-Datompub.docs.update=true rewrites
them). Request examples are hand-written and must parse.
- docs/atompub/roller-atompub.rnc: RELAX NG grammar for the roller:* and
thr:in-reply-to elements; the test validates every example against it
and against the RFC 4287/5023 grammars.
- Move the Jing helper into RelaxNgValidator for both schema tests.
* Document the category image and length rules in the AtomPub guide
snoopdave
added a commit
that referenced
this pull request
Oct 10, 2026
#209 (templates, categories and comments over AtomPub) and #211 (AtomPub reference guide) were merged into their stacked base branches after #210 was squash-merged into master, so their changes never reached master. This commit applies them: the tree is that of replace-propono-atompub at 95d2419, which is master plus #209 and #211.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #209 → #210 (base:
atompub-templates-categories-comments). Review only the commit on top of it.Adds
docs/roller-atompub-guide.adoc, a reference for Roller's whole AtomPub interface, built to PDF with the other guides:curlsession, and schemas.Examples cannot drift from the code:
docs/atompub/examplesare generated fromAtomWriterbyAtomPubDocExamplesTest. The test fails when the committed files differ;-Datompub.docs.update=truerewrites them.AtomReader.docs/atompub/roller-atompub.rnc.Also: the PDF is added to the binary release, the user guide's AtomPub section now points to the guide,
docs/atompub/examples/**is excluded from RAT, and the Jing helper moves toRelaxNgValidator.Checked:
mvn -pl app test(530 tests, 0 failures);assembly-releasebuildsroller-atompub-guide.pdf; an HTML render resolves every include; RAT passes.