# marXiv user guide marXiv is a personal e-print archive modeled on arXiv. It holds the owner's papers, gives each one a permanent identifier of the form `YYMM.NNNNN`, and serves an abstract page, the PDF, and a BibTeX citation for every paper. An automated editor reviews each submission against the [standards for acceptance](standards) and the [style manual](style), then accepts, rejects, or holds it, with a written review either way. Authors writing a paper for this archive should start with the [authoring skill](skill). ## Submitting from the form The submit page takes a title, the authors, an abstract, and a PDF. The primary subject is optional: leave it on "automatic" and the editor assigns one, or declare it and the review judges its fit. Cross-list subjects, comments, MSC and ACM classes, a journal reference, and a report number are optional. A `Replaces` identifier turns the submission into a new version of an existing paper, and a `Revises` submission id records that this attempt answers an earlier one that was not accepted. The public-export checkbox includes the submission in static sites generated with `-public-only`. The checkbox starts unchecked. A replacement inherits its target paper's setting. A revision with no replacement target copies the earlier submission's setting when submitted. After submission the browser lands on a status page that refreshes while the review runs. An accepted paper appears in the listings with its identifier, a rejected submission keeps its review on the status page, and a held submission shows Accept and Reject buttons for the owner to decide. The submitted title and abstract must match the PDF, and the upload must be a PDF of at most 100 MB. ## Submitting from a program POST multipart form data to `/submit`. A successful submission returns 303 with the status page in the Location header, and the trailing path element is the submission id. Poll that status page, or read `submissions//meta.json` in the archive's data directory when running on the same machine. Set `MARXIV` to the archive's base URL, which is the address the owner started the server on. ```sh curl -i \ -F 'title=Paper Title' \ -F 'authors=First Last, First Last' \ -F 'abstract=One paragraph matching the PDF.' \ -F 'subject=math.CT' \ -F 'paper=@paper.pdf;type=application/pdf' \ "$MARXIV/submit" ``` | Field | Meaning | |-------|---------| | title, authors, abstract | Required. Title and abstract must match the PDF's own, at most 300 and 3000 characters. | | paper | Required. The PDF file. | | subject | Optional category code. Empty means the editor assigns one. | | secondary | Optional, repeatable. Cross-list category codes. | | comments, msc, acm, journal_ref, report_no | Optional metadata shown on the abstract page. | | replaces | Optional paper id. Makes the submission its next version. | | supersedes | Optional submission id. Records that this revises an earlier submission. | | related | Optional, repeatable. An identifier, then how this work relates to it. | | public | Optional. `true` includes an initial submission in public static exports. Replacements and revisions inherit their setting as described above. | The server refuses a title over 300 characters or an abstract over 3000, which catches a body pasted into the abstract field. Take both from the compiled PDF rather than retyping them, and check what the extraction produced before sending it. curl's `-F` treats a semicolon inside a value as an option separator. Use `--form-string` for field values that contain semicolons. The category codes appear in the subject menu on the submit page. ## Naming related work A submission may name other papers or submissions and say in its own words how it relates to them. The archive fixes no vocabulary: the comment carries the meaning, and the identifier makes it a link. Each `related` value is an identifier, a colon, and the comment. Repeat the field for several, or in the form put one per line. ```sh curl -i \ --form-string 'related=: supersedes this report' \ --form-string 'related=: assumes the background here' \ ... ``` Replace `` with a published-paper identifier and `` with a twelve-character submission identifier. Both must already exist, and the comment is required, since an identifier alone says nothing. Relations render on both sides. The naming work lists them under "Related work", and the work named lists them under "Named by" with the same comment, so a reader arriving at the older paper is told that something else refers to it. A paper's abstract page shows only papers that name it. A submission's status page shows papers and submissions both. ## Retracting a paper A published paper can be withdrawn without being removed. The abstract page carries a form that takes the reason readers need. The paper, its versions, and its identifier stay in place, so a citation to it keeps resolving, and every page that lists it carries a RETRACTED mark. The same form clears the mark. ## The editor rejects substantive failures A paper fails on substance through unsupported claims, metadata that disagrees with the PDF, or incoherence. The reviewer assumes standard terminology familiar to expert readers and remarks only on paper-specific, ambiguous, or nonstandard language whose meaning the paper does not supply. Subject fit, abstract and body development, citations, secondary metadata, and style also return written remarks that leave the decision alone. The review quotes the specific section, claim, or omission behind every finding. ## Reading the archive Every paper has an abstract page at `/abs/`, which accepts a version suffix such as `/abs/v2`. The PDF is at `/pdf/` with the same suffix rule, and a BibTeX entry at `/bibtex/`. Listings live at `/list//`, where the subject is `all`, an archive prefix such as `cs`, or a category such as `math.CT`, and the period is `recent`, `new`, or a month written `2608` or `2026-08`. Search over titles, authors, and abstracts is at `/search?q=`. ## Public static export The local navigation's “public export” link opens `/public-export`. This page lists every paper once, with a checkbox and the date of its most recent version, newest first. Save selection applies the checkboxes to each listed paper ID and all its versions. Saving changes the selection for the next public static generation. Each paper ID has an independent export setting. Its accepted submissions and submissions naming it in `Replaces` share that setting. A submission's accepted paper ID takes precedence over its replacement target. Submissions with no paper assignment share their setting with revisions that also have no paper assignment. The paper and submission pages provide checkboxes for these settings. Revision links preserve the submission history. Different paper IDs can have different export settings even when their submissions share that history. A new replacement inherits its target paper's setting, including when it also revises a submission with a different setting. Static generation with `-public-only` includes selected papers and submissions in pages, PDFs, search data, listings, and relations. Generated revision links point to included records. A later generation removes files for a paper or submission whose checkbox was cleared. The local server continues to show every record and its revision links. ## Hosting the read-only archive under a path Static generation can place the archive at the root of a host or under a path. The following command writes a copy whose public URL begins with `/archive/`: ```sh ./marxiv -generate -public-only -out /path/to/host/site/archive -base-path /archive ``` The host serves that output directory at `/archive`. Navigation, documents, search, PDFs, and BibTeX links include the same path. HTML page links end in `/` and resolve to directory indexes. An empty `-base-path` produces the root static site. Set `-site-name` and `-site-url` together to put a linked publisher name before marXiv in every generated page header. For example, `-site-name "Smartess Studio" -site-url https://smartess.studio/` links Smartess Studio to its home page. The marXiv name links to the archive. Add `-include-submissions` to publish a read-only copy of the public submission history. The generated copy contains submission status pages, uploaded PDFs, reviews, revision links, and event names and times. It excludes submission forms, owner decisions, re-review controls, and diagnostic error details.