Comments (3)
Authorship
Currently the manual doesn't mention any author(s). I think that having a base author established is important, especially for the Copyright statement (which might be required when submitting the eBook to some book portals or services).
Being a collaborative work, it could have "various authors" — in Italian we use "Aa.Vv." (auctores varii) to indicate this, which has its English counterpart in the "Vv.Aa." acronym (rarely used though). But having established the base author(s), we could employ something like "Thomas Nilefalk et al.".
IMO, regardless of the authors displayed in the book's front matter, the Copyright statement needs to be traceable to some individual(s) or organization.
from alan-docs.
OK @thoni56, I've fixed all pending tasks and only need to remove the -CR
from the document version and we're ready to merge into master
. But first I wanted to discuss with you the metadata addition and some other minor details.
Metadata
Here's the current state of the document metadata:
:doctitle: The ALAN Adventure Language Reference Manual
:version-label: ALAN
:revnumber: Beta7-RC
:revdate: September 22, 2020
:revremark: New AsciiDoc Reprint
:author: Thomas Nilefalk
:email: [email protected]
[...]
// HTML METADATA
:keywords: alan, if, interactive fiction, game, text adventures, programming
:description: pass:q,r[*The ALAN IF Manual* -- The official reference manual \
for the ALAN Adventure programming language for creating Interactive \
Fiction text-adventures.]
Which produces the following Heading and byline:
The ALAN Adventure Language Reference Manual
Thomas Nilefalk — [email protected] — Alan Beta7-RC, September 22, 2020 | New AsciiDoc Reprint
I thought of using the :revremark:
to show the "New AsciiDoc Reprint" comment on the document byline, since it's a "special edition" of the Manual (like we could do for anniversaries, etc.). But of course, we can remove it if you don't like.
HTML Specific Metadata
In the HTML source, you'll see the keywords
and description
metadata:
<meta name="description" content="<strong>The ALAN IF Manual</strong> — The official reference manual for the ALAN Adventure programming language for creating Interactive Fiction text-adventures.">
<meta name="keywords" content="alan, if, interactive fiction, game, text adventures, programming">
For the description, I've used the <bold>
style for the first part, to make it stand out in search engine results. Also, I hope the text is fine.
PDF Issues
Please note that in the PDF document the custom definition of :version-label:
to ALAN
(in order to show ALAN Beta7
as the version number) doesn't work, and it shows instead:
Revision Beta7-RC
There isn't much I can do about it because it's one of those differences between Asciidoctor and DocBook that can't be worked-around. Maybe in the future we might look again into the native Asciidoctor PDF backend, which has been improved since our last tests, and possibly fixed those problems for which we had discarded it at the time.
Preamble
I though of leaving a document Preamble section, although I've cleaned it up in view of the official release. The idea is that the Preamble could contain a summary introduction to each specific edition, highlighting its new features.
In this case, I focused on the fact that it's the first public release of the new "version":
This is the first public release of the new version of the ALAN Manual, ported to AsciiDoc by Tristano Ajmone. The new edition is now availble in HTML and PDF format, featuring contents updates and many improvements, like syntax highlighting of Alan code examples.
This document is subjected to the Artistic License 2.0 terms.
Also, the "Artistic License 2.0" text now links to "Appendix I", which contains the full license text, instead of the license file on the repository.
So, let me know if we need to change anything before releasing.
When we're good to go I'll just do one more commit, removing the -RC
from the Beta7-RC
in :revnumber:
, and then merge into master
.
Also, another important detail, the merge strategy ...
Should we just merge, or should we squash?
If we merge, we should then keep the dev-man
branch alive, to prevent all the temporary dev commits to end up in master
— and, from what I understand, there's no reason why dev-man
shouldn't be a long-standing branch, that we keep alive for the whole development cycle, merging into master
whenever a public release is ready.
On the other hand, if you want complete separation between master
and dev-man
we should then squash into a single commit, and then squash dev-man
on master
to keep it in synch — but I'm not sure how good this is going to be in order to keep it rebaseble on master
in the course of time.
I'm not sure which strategy is better, so I leave to you the choice — just let me know how to handle it!
from alan-docs.
I thought of using the :revremark: to show the "New AsciiDoc Reprint" comment on the document byline, since it's a "special edition" of the Manual (like we could do for anniversaries, etc.). But of course, we can remove it if you don't like.
I like it. It indicates to the observant reader, at least, that there is something new going on.
Should we just merge, or should we squash?
My thinking was along keeping the dev branch alive, with merging for every SDK release and continuous rebase to keep it easily mergeable. But I'm no expert here, and don't know who to ask (except perhaps StackOverflow ;-).
My suggestion is to go with merging/rebasing of the long-lived dev-branch. If we find troubles along the way we'll re-assess, learn and change.
Cominchiamo!
from alan-docs.
Related Issues (20)
- Switching to the Rouge Highlighter HOT 10
- ALAN Manual Is Not Highlighted
- MANUAL: Fix MESSAGEs
- Describe how nested containers are (not) handled wrt. limits HOT 1
- Post-Rouge Updates
- Add Conversion Guide to Website HOT 2
- HLJS: Missing Alternative ALAN Themes
- Highlight ALAN: Add Block Comments Support HOT 1
- Highlight.js ALAN: Add Block Comments Support
- XSL FOP: Missing Alternative ALAN Themes
- Update document preamble for the manual HOT 6
- Manual: Explain VERB Definitions With Multiple IDs
- ALAN Manual: Update to Beta8 HOT 8
- Mention How the AGAIN Message Is Tied to VISITS HOT 3
- ALAN Manual: Update Swedish List of NOISE WORDS
- ALAN Manual: Add Parts & Make Code Prose-Cased HOT 6
- Sass Themes: Fix Operators Colouring HOT 1
- Revise Ch 5. Running An Adventure
- Spurious Diagram Images in 'published' Branch HOT 1
- Adopt New Official Extensions for ALAN3 Solution and Transcript Files
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from alan-docs.