Document LLVM work coming up in BETA 984. - #199
Merged
Merged
Conversation
Jon's contribution exactly as he sent it, so that every later commit in this series reads as a diff against his own text. - docs/LLVM/Getting-Started.md is message.txt, byte for byte. message.txt supersedes the Getting-Started.md inside LLVM.zip. The zip's copy is encoded as Windows-1252 rather than UTF-8, which is why its superscript 1 and curly apostrophe showed up as replacement characters. Decoded that way, it differs from message.txt only in that message.txt moves "Features not yet supported" up, renames it "Current limitations", and adds the note about Windows 7. - docs/LLVM/Images/llvmdoc1.jpg and llvmdoc2.jpg are the zip's two screenshots, byte for byte. Nothing else changes here. The files sit in the folder that the next commit turns into a top-level section, and this commit does not build on its own: the page has no frontmatter yet, and the build's publish allowlist deliberately refuses a .md file without it.
This answers "what does a new top-level section need besides its folder". Four things, and no build check asks for the first three: 1. A nav_order between its neighbours. Features was 6 and Reference Section 7, with no whole number free between them, so Features moves to 5 and LLVM takes 6. 2. A part in docs/_book.yml, placed right after Features. The PDF book contains only the pages a part claims and leaves every other page out without a warning; that is why the IDE, Challenges and Videos sections are not in the book. 3. A line in "Where content lives" in docs/Documentation/Authoring.md, the contributor guide's list of sections. 4. The page-count rise that the build writes to builder/page-baseline.json (912 -> 914 pages, 248 -> 250 static files), committed together with the pages. The pages themselves: - docs/LLVM/index.md is new: the section's landing page, at /LLVM/. It lists its topics by hand and sets has_toc: false; without that, the page template appends a second, automatic list of the section's pages. - Getting-Started.md gains frontmatter: title "Getting Started with LLVM", parent LLVM, permalink /LLVM/Getting-Started. - Its two image links change from ../Images/ to Images/. The zip puts Images/ beside the page, so from docs/LLVM/ the link ../Images/ pointed at docs/Images/, which does not exist. WIP.md records the checklist above for the next top-level section.
Changes of form only. The changes of substance are in the next commit,
so that the two can be reviewed separately. The conventions come from
WIP.md and docs/Documentation/Authoring.md.
- Heading levels. The page title is a single #, its sections are ##,
and the italic pseudo-headings *OS Support* and *Language support*
become ### headings. The page's section links, the accessibility
check's heading-order rule and the PDF book's bookmarks all rely on
the levels.
- A one-sentence summary under the title, as the site's pages open.
- Code fences are tb, not vb6. The site's highlighter does not know
vb6, so both samples rendered as plain text, and the build warned
about it. The "..." placeholder lines became "' ..." comments, which
makes both samples valid twinBASIC that the compiler can check; a
later commit has it do so.
- The CPU feature table was preformatted text. It is a real table now,
which a screen reader can navigate and which scrolls inside its own
box on a phone. Its superscript-1 footnote became a sentence under
the table.
- Lines ending in a backslash (forced line breaks) became lists. The
three IDE options and the +llvm, +optimize and +optimizesize flags
are definition lists, which is how the site presents options and
parameters.
- UI labels are in bold and spelled as the IDE shows them, for example
"LLVM Compiler: Maximum number of threads".
- Links to what the text names: Project Settings, the Tools menu and
IDE Options, the Debug Console, the CompilerOptions attribute, and
the FAQ's answers on editions and on reporting bugs.
- The CPU-feature warning is an IMPORTANT callout. A program that uses
a feature its CPU lacks crashes, and the site keeps IMPORTANT for
what affects correctness.
- Alt text describes what each screenshot shows, including the notes
printed in the dialog, instead of starting "A screenshot of".
- Plain English for readers who are often not native speakers: long
sentences split; "error propagation up through parent procedures"
as "passing an error up to the calling procedure"; "tB" as
twinBASIC; "employs" as "uses"; "check" a box as "tick" and
"license" as "licence", which is how the rest of the site spells
them; the literal curly apostrophe as a plain one, since the build
makes quotes typographic.
- "CPU Features details" is now "CPU feature availability", which a
new cross-reference in "LLVM in twinBASIC" links to.
The closest this commit comes to changing the meaning: "This will be
addressed soon" became "A fix is planned", because the page will
outlive "soon"; and "Future of LLVM support" keeps its content but
loses the first person ("we") and "Stay tuned", which the site's style
rules exclude. It is two sentences now.
1. A note under the title: the page describes BETA 984 and later. The docs go live before 984 is released, and a reader still on 983 would find none of these settings. Checked against the 983 install: its IDE has no LLVM setting in Project Settings or in IDE Options. 2. SSE4.1 first shipped with Intel's Penryn in 2007, not with Nehalem in 2008. Nehalem (November 2008) added SSE4.2, which the row below already gives correctly. Penryn launched in November 2007 with the Core 2 Extreme QX9650 and the Xeon 5400 series, and every Penryn processor has SSE4.1: https://en.wikipedia.org/wiki/SSE4 https://en.wikipedia.org/wiki/Penryn_(microarchitecture) https://en.wikipedia.org/wiki/Yorkfield https://www.theregister.com/2007/10/29/review_intel_qx9650_penryn/ https://en.wikipedia.org/wiki/Nehalem_(microarchitecture) 3. A note that the IDE cannot debug code compiled with LLVM, so LLVM under Compiler Options (DEBUG) is not recommended. This is the IDE's own advice, printed in bold under that section in the first screenshot; the text did not say it. 4. LLVM is built into twinBASIC: a separate LLVM installation is not needed, and twinBASIC ignores one if present. The site already said so on the CompilerOptions attribute's entry; a reader of this page should not have to find it there.
check_build asks examples.bat, the harness that compiles the
documentation's own code samples, to compile a fence. It is not part
of the normal build, because it needs a twinBASIC install. It is run
on demand, and a pull request that adds or changes a sample pastes its
summary line into the description.
Both samples compile on BETA 983, the newest build installed here, and
so does every other marked sample in the documentation:
examples.bat
check_examples: 1119 sample(s), 1119 compile, 0 finding(s), 115.1s -- clean
What that proves is limited. The harness asks only the compiler's
front end, which accepts [CompilerOptions] with every CPU flag in it.
Nothing runs LLVM code generation, so a clean run says nothing about
the BETA 984 behaviour the page describes.
WIP.md and WIP.ExamplesBuild.md update their counts: 1,117 -> 1,119
samples marked, and 1,169 -> 1,171 fences.
Six existing pages said something about LLVM that BETA 984 makes out
of date, or said nothing where a reader would look for it.
- Reference/Attributes.md, the CompilerOptions entry:
- says what the attribute does: it sets the LLVM options for one
procedure in place of the project's, and an empty string turns
LLVM off for it, as the new page describes;
- no longer says +llvm cannot compile objects, strings or dynamic
arrays. The new page says that in 984 every language feature works
except passing an error up to the caller, which supersedes it;
- drops +optimizespeed. The BETA 983 compiler knows +llvm, +optimize
and +optimizesize and contains no such string, and the 984 page
does not list it. If 984 has it after all, it goes back;
- gains the CPU instruction-set flags, linking to the new page's
list;
- loses an invisible U+2060 WORD JOINER, and gets back the space
missing from "LLVMinstead".
- IDE/Project Settings.md lists the settings in the dialog's order and
stopped at Feature Flags. It gains Compiler Options (BUILD) and
Compiler Options (DEBUG), which follow Feature Flags in the dialog,
both linking to the new page.
- IDE/Menu/Tools.md lists "Flush the LLVM compiler cache", and points
to the new page for the three LLVM Compiler IDE options. Its
screenshot still shows the older menu, with IDE Options only.
- Features/Project-Configuration/Compiler-Options.md gains a short
LLVM section linking to the new page.
- Miscellaneous/FAQs.md: the answer on EXE size said LLVM compilation
was "coming soon"; it now says that in the paid editions LLVM can
reduce EXE size with "LLVM: Optimize for smaller filesize". In the
answer on cost, "advanced optimized compilation", which the free
edition lacks, links to the new page.
- index.md, the home page, gains a short LLVM section between the
Features and Reference entries, matching the order in the navigation.
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
2 participants
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.
No description provided.