<PubNote> is an open-source resource for visualizing, preparing, and working between the angle brackets of XML metadata content that is submitted to and distributed from OLSPub in Europe and PubMed in the US.
<PubNote> is conceived, initiated, and maintained by Ireland-based Réalta Online Publishing Solutions Limited – https://RealtaOnline.com. Réalta is a purveyor of fast, accurate, and quality online and API publishing services for tailored single-source JATS XML publishing with high fidelity to PDF, HTML, and DOCX output formats. Contact us for your off-site online JATS publishing needs without the maintenance of on-site publishing software.
<PubNote> consists of these out-of-the-box XML metadata tools for Windows, Shell, and Mac invocations:
- PubNoteInCheck – validation of PubMed submission XML against the submission DTD
- PubNoteInText2XML-xx - conversion of PubMed submission text rendering into submission XML
- PubNoteInDraft – drafting of PubMed submission text and XML from JATS article XML (outlined for Phase 3 of this project)
- PubNoteOutCheck – validation of PubMed distribution XML against the distribution DTD
- PubNoteOutExtract – extraction of PubMed distribution XML documents from a set XML document
- PubNoteOutIndent – indentation of PubMed distribution XML documents from a single or a set XML document
- PubNoteXML2Text-xx – transform PubMed XML document into text without using markdown for mixed content
- PubNoteXML2TextMarkdown-xx – transform PubMed XML document into text using markdown for mixed content
- PubNoteRender-xx – visualization of PubMed submission or distribution XML to PDF, HTML, DOCX, text without markdown, and text with markdown
Suffixes -xx:
- "-en"=English (A4), "-us"=English (US-letter), "-de"=German, "-fr"=French (others welcome!)
- "-short"=short labels for use in making the text files smaller than with XML or natural language labels
- absent suffix: use XML names as defined in the document models as the labels
<PubNote> works in four user interfaces, shown in this example where the file PubMedOut-4.xml (copied from the repository test directory to a base directory also named "test") is being rendered using PubNoteRender-de (found in the user Crane's local copy of this git repository) (Click any image to enlarge.):
- illustrated DOS invocation:
u:\git\crane\PubNote\windows\PubNoteOutRender-de.bat PubMedOut-4.xml - illustrated shell invocation:
sh ~/u/git/crane/PubNote/shell/PubNoteOutRender-de.sh PubMedOut-4.xml
<PubNote> publishes the original PubMed XML with multiple-language labels (shown here in English) in PDF, HTML, DOCX, and, if useful, indented XML, without disturbing the original XML (Click any image to enlarge.):
Also included is a simple text file rendering following particular syntax conventions recognized in the conversion from text to XML. Each of the languages is available to be used to prep for editing and conversion (XML, English, German, French, and short ):
This labeling supports round-tripping a PubMed in (submission) XML document for editing by non-XML subject matter experts who can use the simple text labels instead of XML angle brackets and syntax:
The test/ directory has anonymized sample PubMed in (submission) and out (distribution) XML files for testing. You can copy these XML files into a temporary directory outside of the git repository and use them for tests.
This test directory also includes the results of all invocations, found in subdirectories, so that you can see all the completed reports without having to execute anything.
To install <PubNote> as a GitHub user, simply clone or fork the repository to a local repository on your system:
git clone https://github.com/realtaonline/PubNote.git
You can then invoke the tools directly from the appropriate shell/ or windows\ subdirectories, or use drag-and-drop as shown above. No build step is required, however, you do need Java 11 or higher installed in your environment.
If you are not a GitHub user, from the latest release package 
- for the Windows, DOS, and shell environments download the ZIP file directly from the browser:
- for the Mac environment use
curlin Terminal to download the ZIP file (a browser download will prevent the Mac apps from executing):curl -LO https://github.com/realtaonline/PubNote/releases/latest/download/PubNote-latest.zip
Please see the wiki tab above for these instructions, more information, and frequently-asked questions.
Please see the discussions tab above for open discussions and infrequently-asked questions.
The US-based PubMed has grown over the years into a resource of more than 38 million citations of published biomedical literature. Each abstract is available from PubMed as a summary XML document valid against a simple abstract-oriented DTD for distribution. The PubMed system itself only accepts summary XML documents valid to a different simple abstract-oriented DTD for submission.
It is estimated that 8 million of these citations are to journal articles authored in JATS XML to satisfy the inclusion requirements in the PubMedCentral (PMC) and European PMC databases, to satisfy US National Institute of Health (NIH) public access policy for such inclusion, or already satisfying the use of JATS internally by publishers even when not publicly shared as an XML document.
In Europe in May 2025, the new OLSPub (Open Life Sciences Publishing) project was established by the publicly-funded ZB Med in Germany. This project strives to protect the wealth of information in PubMed in a parallel open database maintained outside of US jurisdiction. Ready for the future, the project already contains all existing PubMed data and is ready for any additional data publishers may wish to contribute directly. That project is getting a lot of attention.
This <PubNote> project, conceived in the spirit of OLSPub for jurisdictional independence, open data, and publisher empowerment, is an open-source resource for working with PubMed XML metadata. The target users are small publishers who may not have the XML tools to create, edit, or render the metadata.
The entire visualization code base for <PubNote> is oriented around simple and shallow metadata XML documents, a contrasting nature to the rich and deep JATS document model. Whereas JATS describes elaborate prose-oriented nested structures intended for branded distribution, PubMed describes only flat metadata structures intended only for internal reviews, indexing, and search.
Nevertheless, these simple PubMed metadata structures are in arcane XML syntax which can be discomfiting to some users who may be allergic to angle brackets. <PubNote> seeks to make working with and reviewing the content of these structures easy for all users. Moreover, non-XML-aware subject matter experts can use a simple text format either with XML names or natural language labels to compose or edit submission metadata documents using a simple text editor and syntax.
In summary, <PubNote> aligns with OLSPub's objectives by offering open-source tooling to inspect, edit, and validate the XML metadata formats used in its submission and distribution workflows. This free tool aims to aid metadata quality assurance and empower non-technical contributors and small publishers with limited budgets, thus improving their trust in meeting specialized XML obligations.
Phase 1 of this project was released to the public in November 2025. Phase 2 was released in June 2026. Phase 3 is awaiting public feedback.
The basic flows interacting with OLSPub and PubMed are simple:
- A valid PubMedIn XML submission document is forwarded for inclusion in the OLSPub and/or PubMed database
- A valid PubMedOut XML distribution document is obtained for processing
2a. exported directly from the OLSPub and/or PubMed database according to some criteria, or
2b. extracted (with or without added indentation) using the PubNoteOutExtract process against one or more valid PubMedOut XML distribution documents, such as from an ~200MB XML single article set document of 30,000 article documents unpacked from a ~20MB ZIP file from the PubMed FTP site
The <PubNote> visualization/validation environment wraps around these two "in/submission" and "out/distribution" XML documents, giving users tools to create, confirm, and consume the information.
- For human metadata entry, the user can edit a simple text expression of in/submission content according to syntax rules
- PubNoteInText2XML-xx converts a simple text expression of in/submission content into a PubMedIn document (not suitable for PubMedOut documents)
- Optionally, the user uses PubNoteDraft to create a PubMedDraftIn document as a starting point from a distillation of multiple JATS XML documents into a draft (Phase 3)
- For human review, PubNoteRender formats the information found in a PubMedIn document
- Optionally, PubNoteInCheck can validate a PubMedIn document against the
PubMed.dtd - Optionally, a PubMedIn document can be checked using the NIH online business rules validator
- Optionally, PubNoteOutCheck can validate a PubMedOut document against the
pubmed_250101.dtd - For human review, PubNoteRender formats the information found in a PubMedOut document
The visualization process in PubNoteRender produces human-readable documentation:
- PubMedOut and PubMedIn documents are rendered to various formats:
11a. Simple text is created using PubNoteXML2Text-xx following the specific PubNoteInText2XML-xx syntax conventions
11b. XSL-FO is created with all of the content to be presented downstream in PDF, HTML, and DOCX - XSL-FO is transformed into PDF for print purposes:
12a. – a conforming XSL-FO 1.1 processor directly produces the output (not part of this repository)
12b. – a non-conforming XSL-FO 1.1 process requires a transformation to make a suitable subset XSL-FO - XSL-FO is transformed into XHTML for browser display
- XHTML is transformed into SWPX (Simple Word Processing XML) for word processing purposes
- The Wordinator tool combines SWPX and a Microsoft DOTX template to produce a DOCX file
- Optionally, PubNoteOutIndent processes a PubMedOut document into an indented XML output
For questions, suggestions, comments, and contributions we invite you to create issues and pull requests, both of which are accessible in tabs in the GitHub web page header. Eager qualified contributors are invited to introduce themselves for consideration in joining the team.
With phases 1 and 2 complete, phase 3 is awaiting the determination of what to distill from JATS XML documents into draft PubMed in (submission) documents.
In particular, improvements and additions to the label language translations for xsl/xlate/ are most welcome.
The numeric versioning of this project <major/>.<minor/>.<patch/> pattern according to Semantic Versioning:
<major/>— increased when existing usage breaks due to changes<minor/>— increased when new features are added that extend functionality without disrupting existing use (i.e. backward-compatible additions).<patch/>— increased when errors are corrected or documentation is improved, without changes to features or behaviour (i.e. bug fixes and cosmetic adjustments).
This approach helps indicate whether an update is likely to affect existing workflows or simply enhance the project.
Please review the following documents to understand repository governance, expectations, and support channels:
- ROADMAP.md – looking ahead
- CHANGELOG.md – looking back
- CONTRIBUTING.md – how to propose changes or fixes
- CODE_OF_CONDUCT.md – expectations for respectful collaboration
- SECURITY.md – how to report vulnerabilities responsibly
- SUPPORT.md – where and how to request help or ask questions
Further resources are available via the tabs above:
- See the Wiki for installation instructions, additional details, and frequently asked questions.
- See the Discussions for ongoing conversations and infrequently asked questions.
At this time the project manager is G. Ken Holman, a long-time XML community contributor and the XML Technology Lead at Réalta Online Publishing Services Ltd. Ken's conference papers at JATS-Con 2020/21 and JATS-Con 2023 offer some insights into the implementation of this project using principles found in Réalta's JATS publishing service offering.