Update document preamble for the manual

Question

Update document preamble for the manual

thoni56 opened this issue 3 years ago · comments

The current pre-amble was written in the transitional days, when the "purpose" was to create an AsciiDoc conversion.
The current state is that this is the documentation.
So I suggest that text should be focused on that.
Or maybe not be shown at all, although an "About this document" section might still be a good idea.

I also noticed that the revnumber is Beta8-snapshot.
The document generated from master should always have the latest release as revnumber and no "snapshot" as that should point to the release of the system it refers to.
revdate on the other hand might (should?) change, but I forgot what we decided on how and when to do this. (I'll look it up.)

As Beta8 is nigh the rev-info need not be fixed now, as we will do that with the merge anyway.

Tristano Ajmone · Answer 1 · Sat Aug 28 2021 20:12:04 GMT+0800 (China Standard Time)

The current pre-amble was written in the transitional days, when the "purpose" was to create an AsciiDoc conversion.
The current state is that this is the documentation.
So I suggest that text should be focused on that.

I believe it was indeed changed slightly when the book reached the final version, but the text indeed now always points to the fact that it's "the first public release of the new version", which is no longer the case.

Any proposals on how to change it?

Or maybe not be shown at all, although an "About this document" section might still be a good idea.

I think that it would be a good idea to have some special section with introductory info. AsciiDoc allows the following special book sections:

colophon
dedication
acknowledgments
preface

We currently aren't using any of these special book sections, just the Preamble which isn't really a section at all but just a space where to add whatever extra details might be useful (and which I believe should be kept too).

I also noticed that the revnumber is Beta8-snapshot.
The document generated from master should always have the latest release as revnumber and no "snapshot" as that should point to the release of the system it refers to.

This is probably something that we can simply edit directly in the document header, at a branch level, after all whenever the doc in master bumps up to the latest Beta, the doc in the dev branch also bump up to the same version plus -snapshot. Maybe later on we could have Rake handle this on how behalf.

revdate on the other hand might (should?) change, but I forgot what we decided on how and when to do this. (I'll look it up.)

We didn't, the Issue/Discussion with the proposals is still waiting for a reply. My latest suggestion was to remove the revdate from the document and just let it be autodefined by Asciidoctor at conversion time. After all, now this only affects the documents published on the website, so whichever date is shown is always going to be later than the previous version.

As Beta8 is nigh the rev-info need not be fixed now, as we will do that with the merge anyway.

True, then shall we agree that when Beta8 is out we'll:

Change revnumber in dev branch to Beta8
Merge into master.
Change revnumber in dev branch to Beta9-snaphot

and then the cycle goes on like this, until we decide on an automated way of handling it.

PS: Please remember that (as I noted elsewhere) I can't use the publication script to automatically handle all these details, because currently I can only use Git over HTTP, and the script uses SSH. I hadn't had the time to look into how to enable SSH on Win OS (i.e. without facing trouble), so if you move the logic on how to handle those attributes into the publish.sh script I won't be able to benefit from it right now.

Thomas Nilefalk · Answer 2 · Sat Aug 28 2021 22:41:19 GMT+0800 (China Standard Time)

Pre-amble/intro

Any proposals on how to change it?

Or maybe not be shown at all, although an "About this document" section might still be a good idea.

I think that it would be a good idea to have some special section with introductory info. AsciiDoc allows the following special book sections:

colophon

dedication

acknowledgments

preface

We currently aren't using any of these special book sections, just the Preamble which isn't really a section at all but just a space where to add whatever extra details might be useful (and which I believe should be kept too).

Well, it was the text of the pre-amble that shows up after the title in the HTML that I reacted upon. It looks like it is totally unstyled. It does not show in the PDF.

I actually don't know what would be appropriate to have here. Appreciation for your conversion work should be somewhere else, I think (acknowledgments?).

Revnumber/revdate

I also noticed that the revnumber is Beta8-snapshot.
The document generated from master should always have the latest release as revnumber and no "snapshot" as that should point to the release of the system it refers to.

This is probably something that we can simply edit directly in the document header, at a branch level, after all whenever the doc in master bumps up to the latest Beta, the doc in the dev branch also bump up to the same version plus -snapshot. Maybe later on we could have Rake handle this on how behalf.

revdate on the other hand might (should?) change, but I forgot what we decided on how and when to do this. (I'll look it up.)

We didn't, the Issue/Discussion with the proposals is still waiting for a reply. My latest suggestion was to remove the revdate from the document and just let it be autodefined by Asciidoctor at conversion time. After all, now this only affects the documents published on the website, so whichever date is shown is always going to be later than the previous version.

Good. Yes, letting the publishing define the revdate is a very good choice. Although I think we agree that it would be a good thing if the date (or some other marking) would change when the content have changed, but let's leave that for now.

(I don't know if you mean this discussion, if so it's quite entangled, but if this question was the last outstanding issue I think that we can conclude that discussion. Still need a wiki-page on publishing strategy, I guess.)

Beta8

As Beta8 is nigh the rev-info need not be fixed now, as we will do that with the merge anyway.

True, then shall we agree that when Beta8 is out we'll:

Change revnumber in dev branch to Beta8

Merge into master.

Change revnumber in dev branch to Beta9-snaphot

and then the cycle goes on like this, until we decide on an automated way of handling it.

Exactly.

I've changed my mind and will re-publish this beta7 content and I'll fix the revision (and this time change date manually) just because it's easy. And refressh my memory on how to do that.

SSH on Windows

PS: Please remember that (as I noted elsewhere) I can't use the publication script to automatically handle all these details, because currently I can only use Git over HTTP, and the script uses SSH. I hadn't had the time to look into how to enable SSH on Win OS (i.e. without facing trouble), so if you move the logic on how to handle those attributes into the publish.sh script I won't be able to benefit from it right now.

Since OpenSSH should be available on Windows now, it should be fairly straight forward. I don't know how to stay away from any "trouble", but here are some simple instructions (if you need them...):

Generate ssh-keys
I opened a command prompt and ran ssh-keygen which generates the two part key files in %HOME%/.ssh
Open your personal settings on GitHub and open the SSH/GPG keys tab
Add a new key, which you name something so that you know where it connects from, then copy the content from the private key file in the text area.

If you are just accessing GitHub it should now simply be possible to clone using the SSH-version of the URL instead.

(https://phoenixnap.com/kb/generate-ssh-key-windows-10)

Tristano Ajmone · Answer 3 · Sun Aug 29 2021 00:49:50 GMT+0800 (China Standard Time)

Well, it was the text of the pre-amble that shows up after the title in the HTML that I reacted upon. It looks like it is totally unstyled.

Yes, that's it. By default, the Preamble is just a single paragraph with smaller font size; but you can extend it by enclosing it in a generic block __ if you want to. I usually either don't style it at all or enclose it in an Example block, to make it clear it's an aside.

It does not show in the PDF.

Mhhh, probably then that's a limitation of DocBook, which doesn't support all the AsciiDoc features (I never quite understood why AsciiDoc focused so much on the DocBook format, but I guess this goes back to the original Python version and attempts to find an easy way to create DocBook documents, which were quite popular back then).

I actually don't know what would be appropriate to have here. Appreciation for your conversion work should be somewhere else, I think (acknowledgments?).

Indeed, the Acknowledgments section is good to have and all credits to contributors should go there. But I still think that a simple sentence should be kept in the Preamble, clarifying that this is the new official document version — as for the PDF not showing the Preamble, my guess is that when the asciidoctor-pdf gem/toolchain will finally reach v2.0 we'll be able to switch to it and make use of all the cool ADoc features we're missing out right now (also, Rouge is supported there too).

Although I think we agree that it would be a good thing if the date (or some other marking) would change when the content have changed, but let's leave that for now.

Yes, but most of these considerations referred to when the docs were tracked by the repository at each commit. Now that they are seldom updated on the website, we could make things easier and just use whatever date the docs were built at. This might confuse the user who won't be sure if it's worth downloading manually the docs to benefit from any changes, but it's also true that end users should probably just update the docs with each new Beta, and if they are Alpha users, they'll probably be better off just reading it online, or even better clone the repository and build them locally.

(I don't know if you mean this discussion, if so it's quite entangled, but if this question was the last outstanding issue I think that we can conclude that discussion. Still need a wiki-page on publishing strategy, I guess.)

Yes, that one, and quite entangled indeed. A Wiki page for the strategy is a good idea. I'll look into it.

I've changed my mind and will re-publish this beta7 content and I'll fix the revision (and this time change date manually) just because it's easy. And refressh my memory on how to do that.

Good idea. Also, since Beta updates are not so frequent, I don't think that manually fixing that attribute each time is going to be a huge deal, as long as we remember to.

Since OpenSSH should be available on Windows now, it should be fairly straight forward. I don't know how to stay away from any "trouble", but here are some simple instructions (if you need them...):

Thanks for tips, I appreciate them. I didn't realize that OpenSSH is now native on Win, and that was my main concern really (updating it, etc.). The rest is fairly simple (the setup, the GitHub part, etc.). The only reason I chose to use HTTPS was because I always fear that an HD crash will make me loose the SSH keys — sure, backups! but there are so many things to backup that I tend to forget what's were anyhow. 😭

Thomas Nilefalk · Answer 4 · Sun Aug 29 2021 01:44:11 GMT+0800 (China Standard Time)

Thanks for tips, I appreciate them. I didn't realize that OpenSSH is now native on Win, and that was my main concern really (updating it, etc.). The rest is fairly simple (the setup, the GitHub part, etc.). The only reason I chose to use HTTPS was because I always fear that an HD crash will make me loose the SSH keys — sure, backups! but there are so many things to backup that I tend to forget what's were anyhow. 😭

It's not a big deal if you lose your keys, you can just generate new ones, log in to your account and upload them (deleting the old). The issue I have is that I want to have different keys for all the sites I access (corporate, github, websites, ...) and I also use a handful of computers for accessing some of them. I always forget to name them in a way so that I know which is which...

Tristano Ajmone · Answer 5 · Mon Aug 30 2021 16:08:01 GMT+0800 (China Standard Time)

Wiki: Added Strategy Page

Still need a wiki-page on publishing strategy, I guess.

I've created a new Publishing Strategy Wiki page, which will eventually cover all the policies, strategies and technical aspects of how the website is updated. I've also created a new Policies category for documents like this.

For the Discussion on the strategies, see #125

Tristano Ajmone · Answer 6 · Sat Dec 18 2021 09:22:21 GMT+0800 (China Standard Time)

Publish Script: Switched to HTTP

Since OpenSSH should be available on Windows now, it should be fairly straight forward. I don't know how to stay away from any "trouble", but here are some simple instructions (if you need them...):

@thoni56, the problem is not setting up the SSH key, that part worked. The problem is that there's no way to have my Bash memorize the password, and I have to re-enter it at every Bash session and every script invocation.

There are two problems here:

Conflicts between the native Windows SSH agent (from OpenSSL) and the one from Git for Windows, which are both on the sys path.
Some problems with my Git installation, which for some reason has troubles with permissions which prevent it to have full access to some Git folders — the problem was reported on Git for Windows repository over two years ago, but no fix was ever found. Uninstalling and reinstalling Git doesn't fix the problem. I'm not alone in this, other users experience the same. It seems that it's a problem affecting those who had installed a specific version of Git for Windows, which went badly wrong with an updated. The only solution would be to format the harddisk and reinstall Windows, but it seems a drastic measure.

So, in the publish.sh script I've commented out the original line with SSH and added one with HTTP:

git clone -b published https://github.com/alan-if/alan-docs --single-branch
# git clone -b published git@github.com:alan-if/alan-docs --single-branch

I hope you don't mind, but I've already wasted more than 10 hours trying to fix the problem since our last exchange here, and that's more than I can afford on my little free time. I simply use HTTP with Git, and I'm fine with it.

Unfortunately Git is an antiquated tool for POSIX, and the Windows version is a huge monster with over a thousand files, yet not fully compatible with the "original" Git. What can I say, Fossil is a much better tool than Git, comes with a single binary which is truly cross platform (pure ANSI-C/C89 for max Win compatibility), and is much better than Git ... yet, it's corporate decisions that make computer history and decide what's "better" for us developers, so that's the way things are.