App G. Localization #67
Closed
Conversation
This file contains 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
Finally confirmed that asciidoctor-fopub now works correctly with Java versions >= 8 (gradle error fixed). Now the project switches to using Java JDK 12. - Add note about switching to Java 12. - Update alan-xsl-fopub documentation. - Update the submodule pointer to alan-xsl-fopub. For more info, see: - asciidoctor/asciidoctor-fopub#87 - asciidoctor/asciidoctor-fopub#88
Add link to new ALAN repository on GitHub, alongside the Bitbucket link.
In new `writing/` folder add AsciiDoc port of the "Alan Author's Guide" (_The ALAN Adventure Language Author's Guide_), taken from Alan source repository: https://github.com/alan-if/alan/tree/master/doc/manual/writing.odt Document is fully ported, but contents incomplete. It's development moves to this project, replacing its development in the ODT format on the Alan source repository. Closes Issue #48.
Add `.editorconfig` file to enforce ISO-8859-1 on Alan sources and ensure consistent code styling across different editors and IDEs. Also improves Alan sources visualization on GitHub. Form more info, visit: https://editorconfig.org/ Closes #53.
Update all existing Bash and batch build scripts: * Add consistent header info e annotations. * Add public domain note via the Unlicense (where applies). Update all Bash scripts for building PDF docs, and add new ones where missing: * Fix incomplete template path in some script. * Abort if executed under Bash for Windows, due to asciidoctor-fopub not being able to find default template images (e.g. admonitions icons). For more info, See #66.
New `_assets/sh/` folder with reusable Shell/Bash script modules: * `_print-funcs.sh` -- ornamental text color and formatting funcs. Update READMEs accordingly.
Add batch and Bash scripts to update the alan-xsl-fopub Git submodule:
* `xsl-alan-fopub-update.bat`/`.sh`
These scripts first cd to the submodule directory, force checkout master
branch and pull, then also issue a git submodule update command:
git submodule update --remote --merge _assets/alan-xsl-fopub
This ensures that both the local copy of the repository as well as its
submodule pointer are correctly updated.
The batch script also rebuilds all PDF documents that rely on the custom
XSL template:
* `manual/manual.pdf`
* `alanguide/alanguide.pdf`
* `_dev/styles-tests/styles-preview.pdf`
* `_dev/styles-tests/tests-syntax-highlighting.pdf`
* `_dev/styles-tests/tests-typography.pdf`
Run `xsl-alan-fopub-update.bat` to update the submodule pointer to the latest version of alan-xsl-fopub, and rebuild all PDF docs. The template update removes URL footnotes for links, which were being added for the benefit of printed documents -- but looked ugly on PDF docs, which provide active click-able links. Fixes #64.
tajmone
added
📖 Alan Manual
|
App. G is far from complete, but at least this commit provides some new contents on the topic. I'd like to keep this squashed as a single-commit, so if we do make some further changes I'll like to squash all commits before merging into branch I thought that adding to this Appendix a "Useful Links" section made sense, and started by providing links to the Alan Italian project, the sections on natural language of the Inform Designer Manual, as well as some key linguistic topics on Wikipedia. The creations of a links section prompted me to fix the XSL Template so that no URL-footnotes would be created for inline-links (See #64). That might have been useful for printed books, where links are not actively click-able, but I thought that ultimately the PDF docs of this project are destined for screen-reading only (if we ever need to cater for a printable edition, we can always find a workaround for preserving URL footnotes in a sperate PDF).
|
tajmone
force-pushed
the
AppG-i18n-squash
branch
2 times, most recently
from
764e2f1
to
806be0d
Compare
13 tasks
thoni56
approved these changes
Sep 17, 2020
Add proper configurations to `.editorconfig` and `gitattributes`, and polish all Git settings files (See #72). Add `validate.sh` script to check that all sources meet the new code styles conventions, via the EClint tool (Node.js): https://www.npmjs.com/package/eclint Enable Travis CI validation of code styles consistency in every commit and PR, via the `validate.sh` script.
Update the alan-xsl-fopub submodule to the latest version, which added its own EditorConfig settings to prevent the settings of the Alan-Docs repo to be applied also to the submodule's directory. (See #72)
Amend all markdown files until they pass EditorConfig validation via EClint. (See #72)
Amend all shell and batch scripts to pass EditorConfig validation via EClint. (See #72)
Amend all ALAN source files until they pass EditorConfig validation via EClint. (See #72) Most changes consist in adding an empty line at the file end, especially in the ALAN Guide `lib/` and `mylib/` folders. Note that due to EClint's poor support for Latin1 validation, some ALAN sources containing non-ASCII characters are being excluded from econding validation/enforcement via `charset=unset` (See #73).
Amend two AsciiDoc sources that didn't pass EditorConfig validation via EClint. (See #72)
In view of the upcoming Alan 3.0 beta7 release, we shall do all changes to the Manual in this `beta7-prep` development branch, which we'll then squash into master once beta7 is publicly available. Merge branch `handle_elisions` into `beta7-prep` and resolve conflicts on Chapter 5 source by using "theirs" stategy. (See #40 for a discussion on this)
Moved one level up sub-section of §3.17, *Repetition Statements*, which was wrongly portraided as a subsection of *Actor Statements*. Also, change Manual version to v0.1.91-PreReleaseBeta7, which will be kept as temporary development version until ready to merge into `master` when Alan Beta7 is ready (it will become v0.1.91). From now only the date of the manual should be changed.
In §3.7 *SCRIPTs* add links to USE and STOP statements when mentioned in text; although the subjects are strictly realated they are far apart from each other in the Manual, so cross-reference links are most useful here for the reader. And, viceversa, in §3.17 *Actor Statements* > *USE Statement*, add a link to *SCRIPTs*, to allow reader to easily navigate back & forth between these two closely-related sections.
Fix some cross references that were wrongly cased due to the merge of `handle_elisions` branch which still used to old naming convention for Manual sections. (See #40)
Add new batch `_assets/images/SVG_OPTIMIZE.bat` to optimize all SVG
image files using SVGO (Node.js):
https://www.npmjs.com/package/svgo
Optimize `predefined-classes.svg` (57.6%):
14.896 KiB -> 6.317 KiB
In "§3.8. Additions", remove the `[inheritance]` part from the BNF rule of additions, which was only creating confusion to the reader. See discussion on Alan-IF Yahoo: https://groups.yahoo.com/neo/groups/alan-if/conversations/topics/3809 Closes #46.
In new `xtra-docs/` folder, add the AsciiDoc conversion of the docs found in the `doc/design/` folder of Alan repository. See Issue #48.
* Change folder of `xtra-docs/` to `alan-design/` (see #33). * Update `alan-design/README.md` and better specify the context of these docs. * In main README link to new folder in the "Project Contents" section.
First Glossary draft with an initial entry (*stropping*) and some commented-out pending entries TBD later on (Closes #54). Update contents of "§4.2. Words, Identifiers and Names": * Add "Stropping" sub-section. * Add `stropping` anchor. * Add `stropping` Index entry. * Revise and improve contents of this section: * More examples. * Extra admonitions. * Polish text. Clean-up, polish and update README files in Alan Manual directory. Referenced Issues: #36, #50, #54, asciidoctor/asciidoctor#3248.
In "Appendix F.2. Message Explanations" remove references to error 209
("First element in a SYNTAX must be a player word.") which is no longer
a compiler error.
For more info, see: #61 and alan-if/alan@43d21d53.
In various places the word "rule" was formatted as if it was an Alan keyword (i.e. styled as inline code, `Rule`), which it isn't. Amend to it by replacing all occurrences with the word "rule" emphasized (i.e. _rule_) to distinguish it from the general term "rules". Closes #57.
tajmone
force-pushed
the
AppG-i18n-squash
branch
from
806be0d
to
e8bfb3b
Compare
Polish text and add new contents to "App G. Localization": * Provide some general guidelines on how to approach localizing Alan to new languages. * Explain how to exploit *noise* Player-Words and `Synonyms` in i18n to handle articles variations in languages with grammatical gender. * Add "Useful Links" section at the end. * Annotate problems and TODOs (via comments). * Update "G.5. Word Order" (TBD): provide answers to annotated questions regarding the possibility of using `Syntax`es with param in first position. Update TBD admonition note accordingly. (See #61) * Rebuild HTML & PDF Manual. Change document `revremark` to "Beta7 Ed. work".
tajmone
force-pushed
the
AppG-i18n-squash
branch
from
e8bfb3b
to
efc93bc
Compare
Branch Info Not Updating After Force Push@thoni56, I've rebased the branch of this PR on the cleaned up This is the first PR that should be merged (for some reason that I can't remember, but have annotated it so), so that after we can then rebase the other PRs on the updated I'm not sure what to do with the fact that GH is not updating the branch info... Could this lead to problems? Is the PR somehow stuck to previous versions of the branch, and ignoring the force push? Should we just open a new PR from the updated branch? |
|
Maybe I should just merge this branch manually, and close the PR — after all, it was reviewed and approved. I just have a bad feeling about the outdated branch info, and would rather fix this with a manual merge. |
PR Manually MergedDue to the problems with the PR info not being updated after the force push, I've opted to manually merge the PR branch and close this PR. The issue of GH not updating is a known problem, so in this case I deemed it safer to drop the PR procedure. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Polish text and add new contents to Appendix G. Localization:
Synonymsin i18n to handle articles variations in languages with grammatical gender.Syntaxes with param in first position. Update TBD admonition note accordingly. (See Syntax Starting With Param #61)Change document
revremarkto "Beta7 Ed. work".Live Preview links
These links point to the
AppG-i18n-squashbranch, and will work even after force-pushing to the PR: