Topics

[jeffreykegler]

I think the FAQ might be large enough that it would be useful for the readers if there were sections. Potential sections:

• "About Marpa" - the most general info.
• "Error messages" - questions about specific error messages and what to do about them.
• "Problems" - how to deal with various problems that don't easily correlate with an error message.
• "Tricks and techniques" - tricks and techniques for using Marpa, such as the Q on how to parse numbers.
• "How Marpa works" - Q's on Marpa's inner workings.
• "Resources" - resources for further reading, useful links, etc.

[jeffreykegler]

Here's my first try at organizing the Q's by topic:

outline.txt

[ronsavage]

Uploaded for your perusal http://savage.net.au/Perl-modules/html/marpa.faq/faq.html

[jeffreykegler]

I looked at the link, and didn't notice any changes -- in particular, nothing relating to reorganization by topic. Did I miss something?

[ronsavage]

Hi Jeffrey

It looks fine to me. Perhaps it's a browser cache problem?

http://savage.net.au/Perl-modules/html/marpa.faq/faq.html

---

Cheers Ron savage.net.au

On 2023-09-18 12:30, Jeffrey Kegler wrote:

I looked at the link, and didn't notice any changes -- in particular, nothing relating to reorganization by topic. Did I miss something?

[jeffreykegler]

OK, got it this time.

The Table of Contents looks great, but the body of the FAQ has no section headings and the individual FAQs are in the original order, which is now pretty arbitrary.

Many readers will want to read whole sections, all of the "Tips and Tricks" for example. I think the reorganization needs to apply to the body of the FAQ, as well as the Table of Contents.

I'd do this but I don't know how your FAQ pre-processor works.

[ronsavage]

Hi Jeffrey

Ah, I see what you mean. That would require me to rearrange the individual answers into the same order as the TofC.

I will do that next.

---

Cheers Ron savage.net.au

On 2023-09-19 23:58, Jeffrey Kegler wrote:

OK, got it this time.

The Table of Contents looks great, but the body of the FAQ has no section headings and the individual FAQs are in the original order, which is now pretty arbitrary.

Many readers will want to read whole sections, all of the "Tips and Tricks" for example. I think the reorganization needs to apply to the body of the FAQ, as well as the Table of Contents.

I'd do this but I don't know how your FAQ pre-processor works.

[ronsavage]

Hi Jeffrey

Has any of your recent work changed this?

http://savage.net.au/Marpa/html/Marpa.R2.DSL.Structure.html

---

Cheers Ron savage.net.au

[jeffreykegler]

No.

Sent from ProtonMail mobile

-------- Original Message -------- On Sep 20, 2023, 9:28 PM, Ron Savage wrote:

Hi Jeffrey

Has any of your recent work changed this?

http://savage.net.au/Marpa/html/Marpa.R2.DSL.Structure.html

---

Cheers Ron savage.net.au

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

Hi Jeffrey

Currently I'm going thru the questions and re-writing the casual English text such as 'See next question' to explicitly link to the other question, since the re-ordering obsoleted that type of comment.

---

Cheers Ron savage.net.au

[jeffreykegler]

Thanks for doing this! The ability to link to a question is something I will need for what I plan next, after this issue is complete.

Once this issue is done, I hope I can add new sections and questions directly to the .txt file, and submit the changes as a PR, as I have been. That way, if you find the change appropriate, you can easily just merge it.

At that point I will create, and start to populate, a "How to not use Marpa" section. Questions from folks about using other parsers certainly are "frequent" and I will use this section to talk about the best way to use non-Marpa parsers, and when that is advisable.

Sent from Proton Mail mobile

-------- Original Message -------- On Sep 24, 2023, 3:23 AM, Ron Savage wrote:

Hi Jeffrey

Currently I'm going thru the questions and re-writing the casual English text such as 'See next question' to explicitly link to the other question, since the re-ordering obsoleted that type of comment.

---

Cheers Ron savage.net.au

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

Hi Jeffrey

AFAICT All casual cross-references have been updated, with rewording in some cases.

I've changed http://savage.net.au/Perl-modules/html/marpa.faq/index.html to be (internally) titled

The Marpa FAQ Intro

and now the faq itself refers to that. I always found the 2 identical names confusing.

Newest version of the faq itself:

http://savage.net.au/Perl-modules/html/marpa.faq/faq.html

Lastly, the old version is back online at (while we work in it at least):

http://savage.net.au/Perl-modules/html/marpa.faq/old.faq.html

---

Cheers Ron savage.net.au

[jeffreykegler]

Thanks for doing this!

1. In the body the section headers and Q's are at the same header level. Section headers should be one level higher.

2. Q's are no longer numbered in order. I suggest making the tag and Q number distinct, and auto-numbering the Q's. At least for the moment, current tags can keep their old values (#qNNN, where NNN is the old Q number). This means the text of a Q cannot refer to other Q's by number, since that number may change whenever the FAQ is changed, but I think that's OK.

The author of a new Q will have to invent a new, unique, tag. Tags for new questions could be mnemonic instead of numeric.

If you create a separate development branch and push it up to Github, I'd be able to look at your code, which might make my suggestions more helpful.

Sent from Proton Mail mobile

-------- Original Message -------- On Sep 25, 2023, 2:40 AM, Ron Savage wrote:

Hi Jeffrey

AFAICT All casual cross-references have been updated, with rewording in some cases.

I've changed http://savage.net.au/Perl-modules/html/marpa.faq/index.html to be (internally) titled

The Marpa FAQ Intro

and now the faq itself refers to that. I always found the 2 identical names confusing.

Newest version of the faq itself:

http://savage.net.au/Perl-modules/html/marpa.faq/faq.html

Lastly, the old version is back online at (while we work in it at least):

http://savage.net.au/Perl-modules/html/marpa.faq/old.faq.html

---

Cheers Ron savage.net.au

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

OK. I will work on this. Also, I intend to add some CSS so we can prettify the headings. Also, new dev branch pushed.

[ronsavage]

Note: I'm using FF. YMMV.

I have updated the faq. You will probably have to force the browser to reload style.css from the same dir. I do that by typing http://savage.net.au/Perl-modules/html/marpa.faq/style.css into the address bar, and clicking Refresh until the new version appears. You can tell it's the new one by the presence of h3 {...} in the css. Then refresh the display of the faq itself. It's not necessarily very pretty. I'm just getting started on grafting CSS into the faq.txt and style.css files in the guide/ dir. The parser of faq.txt was written by Peter Stuifzand and uses Text::Markdown, which may or may not be a good thing.

Changes have been pushed to the dev branch.

[jeffreykegler]

Looks good. What is "FF"?

Sent from ProtonMail mobile

-------- Original Message -------- On Sep 27, 2023, 11:27 PM, Ron Savage wrote:

Note: I'm using FF. YMMV.

I have updated the faq. You will probably have to force the browser to reload style.css from the same dir. I do that by typing http://savage.net.au/Perl-modules/html/marpa.faq/style.css into the address bar, and clicking Refresh until the new version appears. You can tell it's the new one by the presence of h3 {...} in the css. Then refresh the display of the faq itself. It's not necessarily very pretty. I'm just getting started on grafting CSS into the faq.txt and style.css files in the guide/ dir. The parser of faq.txt was written by Peter Stuifzand and uses Text::Markdown, which may or may not be a good thing.

Changes have been pushed to the dev branch.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

Hi Jeffrey

Gasp! FF => FireFox!

---

Cheers Ron savage.net.au

On 2023-09-28 14:12, Jeffrey Kegler wrote:

Looks good. What is "FF"?

Sent from ProtonMail mobile

-------- Original Message -------- On Sep 27, 2023, 11:27 PM, Ron Savage wrote:

Note: I'm using FF. YMMV.

I have updated the faq. You will probably have to force the browser to reload style.css from the same dir. I do that by typing http://savage.net.au/Perl-modules/html/marpa.faq/style.css into the address bar, and clicking Refresh until the new version appears. You can tell it's the new one by the presence of h3 {...} in the css. Then refresh the display of the faq itself. It's not necessarily very pretty. I'm just getting started on grafting CSS into the faq.txt and style.css files in the guide/ dir. The parser of faq.txt was written by Peter Stuifzand and uses Text::Markdown, which may or may not be a good thing.

Changes have been pushed to the dev branch.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

I am thinking of giving the sections (About Marpa, Error Messages, etc) letter ids (A: About Marpa, ...) so that then the q's within the sections can be numbered as A.1, A.2, ... B.1, B.2, and so on. What do you think?

[jeffreykegler]

I think this is a wonderful idea! Sections should be auto-numbered (auto-id'd?) also, because we'll almost certainly want to introduce new ones, rearrange old ones, etc.

[ronsavage]

I've checked https://daringfireball.net/projects/markdown/syntax and Text::MarkDown (https://metacpan.org/dist/Text-Markdown), but neither offers convenient auto-numbering of things. Searching...

[jeffreykegler]

Maybe you'll end up writing it yourself?

[ronsavage]

Yes. I was hoping Text::MultiMarkdown might help, but nothing I've seen aims at the problem we have, so I've been thinking about a JS solution, and am optimistic, but as yet that's a thought bubble.

[ronsavage]

I've just pushed patches to dev which change the nature of the internal links for Q 1 .. 6. The syntax is awkward in that it involves a lot of repetition of text, but it's a start.

[ronsavage]

These changes were all done manually, by changing scripts/guide.pl to switch from Text::Markdown to Text::MultiMarkdown, and to replace the links for Q 1 .. 6 with the whole text of the link target. For now just notice the simplification of the text in the ToC. Next I'll write a new script which makes the same type of change for all other Qs, and then decide which stage (Perl, JS) to use to simplify things even more.

[jeffreykegler]

Lots of work. Thanks!

Sent from Proton Mail mobile

-------- Original Message -------- On Oct 1, 2023, 1:46 AM, Ron Savage wrote:

These changes were all done manually, by changing scripts/guide.pl to switch from Text::Markdown to Text::MultiMarkdown, and to replace the links for Q 1 .. 6 with the whole text of the link target. For now just notice the simplification of the text in the ToC. Next I'll write a new script which makes the same type of change for all other Qs, and then decide which stage (Perl, JS) to use to simplify things even more.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

Hi Jeffery

Thanx. And lots of thinking has gone into it too.

I've decided to abandon this approach and revert to the main branch version.

Thinking: o Could continue with current rewrite but tools not supportive of arbitrary renumbering o Could design whole Marpa-based grammar for Markdown and hence dialects, but a lot of work [1] [2] o Will switch to numbering all (sic) questions as q999, and have a pre-processor script do the fixup. That way, any re-ordering will not affect the process but will mean over time some questions might get renumbered compared to older versions of the FAQ due to later insertions. Is that ok?

[1] In the bkg, I've written a TV script of 7 episodes of about 25 mins each. It's lecture-format with just me talking. There is an accompanying download at http://savage.net.au/misc/symbolic.language.html. Note that it's a TiddlyWiki as explained via the MainMenu therein. This means it's about 220,000 bytes for all the included code which offers all the features. TiddlyWikis are not my invention, but I wish they were. I'm just about to submit an outline to the Aust Govt's ABC TV station as they are the ones most likely to take it up. There is also a govt supported SBS TV network in Australia who might. Fingers crossed!

[2] I still haven't quite finished my 8,000+ essay of my heart operations, and I've decided to increase the time I spend on it, to get it published before too long.

---

Cheers Ron savage.net.au

On 2023-10-02 01:00, Jeffrey Kegler wrote:

Lots of work. Thanks!

Sent from Proton Mail mobile

-------- Original Message -------- On Oct 1, 2023, 1:46 AM, Ron Savage wrote:

These changes were all done manually, by changing scripts/guide.pl to switch from Text::Markdown to Text::MultiMarkdown, and to replace the links for Q 1 .. 6 with the whole text of the link target. For now just notice the simplification of the text in the ToC. Next I'll write a new script which makes the same type of change for all other Qs, and then decide which stage (Perl, JS) to use to simplify things even more.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[jeffreykegler]

Yes, I always expected questions would change numbers from version to version. And yes, that means folks will have to refer to the question by name, or state "question 42 in version 6.5 dated 25 Dec 2023".

Also sections should change ID's so a new inserted section might make "Section D" become "Section E".

I just went back to the FAQ and note that it does not state a version or date, which I think it will need to. My Timeline, for example, has both.

I look forward to your essay, and will look at the link for your script.

Sent from Proton Mail mobile

-------- Original Message -------- On Oct 1, 2023, 7:02 PM, Ron Savage wrote:

Hi Jeffery

Thanx. And lots of thinking has gone into it too.

I've decided to abandon this approach and revert to the main branch version.

Thinking: o Could continue with current rewrite but tools not supportive of arbitrary renumbering o Could design whole Marpa-based grammar for Markdown and hence dialects, but a lot of work [1] [2] o Will switch to numbering all (sic) questions as q999, and have a pre-processor script do the fixup. That way, any re-ordering will not affect the process but will mean over time some questions might get renumbered compared to older versions of the FAQ due to later insertions. Is that ok?

[1] In the bkg, I've written a TV script of 7 episodes of about 25 mins each. It's lecture-format with just me talking. There is an accompanying download at http://savage.net.au/misc/symbolic.language.html. Note that it's a TiddlyWiki as explained via the MainMenu therein. This means it's about 220,000 bytes for all the included code which offers all the features. TiddlyWikis are not my invention, but I wish they were. I'm just about to submit an outline to the Aust Govt's ABC TV station as they are the ones most likely to take it up. There is also a govt supported SBS TV network in Australia who might. Fingers crossed!

[2] I still haven't quite finished my 8,000+ essay of my heart operations, and I've decided to increase the time I spend on it, to get it published before too long.

---

Cheers Ron savage.net.au

On 2023-10-02 01:00, Jeffrey Kegler wrote:

Lots of work. Thanks!

Sent from Proton Mail mobile

-------- Original Message -------- On Oct 1, 2023, 1:46 AM, Ron Savage wrote:

These changes were all done manually, by changing scripts/guide.pl to switch from Text::Markdown to Text::MultiMarkdown, and to replace the links for Q 1 .. 6 with the whole text of the link target. For now just notice the simplification of the text in the ToC. Next I'll write a new script which makes the same type of change for all other Qs, and then decide which stage (Perl, JS) to use to simplify things even more.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[ronsavage]

Noted!

[ronsavage]

I've pushed dev patches to remove my changes re the new style numbering, so the output html is back to just with new heading sizes and colors.

[ronsavage]

I've pushed a new program, scripts/preprocess.pl, which scans guide/faq.txt and outputs to guide/faq.new. Along the way it identifies the questions and their links. You can run it without it affecting anything else. Usage: perl scripts/preprocess.pl

[ronsavage]

Pushed changes to preproces.pl to perform various error checks.

[ronsavage]

I found an invalid link under 135 When do I use actions and when do I use events? It points to Q 18 but there is no such thing.

[ronsavage]

Some of the link references quote the question but there is a chance the question text could be changed without the link text also being updated. For the moment I have removed such text from the link context. We could either stay with this or change my preprocessor to always insert the question text at the link site. I'm tending to prefer the latter method.

[ronsavage]

All updated code and faq text has been pushed.

[ronsavage]

preprocess.pl takes a -v for verbose option with no value or 0 .. 4. The values produce different output rather that producing more and more output.

[ronsavage]

There is another invalid link under 103 Is Marpa deterministic? It points to 105, which does not exist.

[jeffreykegler]

I can't figure out where the reference to 105 was intended to go. Perhaps just delete that reference?

[jeffreykegler]

Re the reference to Q18 in Q135. I think this was supposed to be a link to Q120 "How do I find out which rule applies at some point in the input stream (e.g. during a pause)?" How it got screwed up I don't know.

[ronsavage]

Hi Jeffrey

Deleted.

---

Cheers Ron savage.net.au

On 2023-10-07 18:45, Jeffrey Kegler wrote:

I can't figure out where the reference to 105 was intended to go.
Perhaps just delete that reference?

[ronsavage]

Hi Jeffrey

Done. Will upload later.

---

Cheers Ron savage.net.au

On 2023-10-07 18:56, Jeffrey Kegler wrote:

Re the reference to Q18 in Q135. I think this was supposed to be a link to Q120 "How do I find out which rule applies at some point in the input stream (e.g. during a pause)?" How it got screwed up I don't know.

[ronsavage]

Can now update version # from command line. Started numbering of sections. Try with: perl scripts/preprocess.pl perl scripts/preprocess.pl -v 2.01 -r 6

[ronsavage]

Another test I need to add is to ensure sections in the ToC are in the same order as in the Body. The validation code already checks they are present in both.

[ronsavage]

Another idea would be to make the section names clickable.

[ronsavage]

I'm thinking of another refinement for preprocess.pl: If the -v switch is missing, do not update the version # in the file. It currently defaults to 1.00. But that's lower priority than renumbering the questions within the sections.

[ronsavage]

The most recent version pushed of preprocess.pl handles the case where the output, guide/faq.new, is used to overwrite the input, guide/faq.txt, in which case the section names already have single alpha [A-Z] ids. IOW: They are not doubled-up in the new output. Next, renumbering questions thruout the text.

[ronsavage]

I've pushed to git the new code and data which I've just announced on our channel #marpa: https://colabti.org/irclogger/irclogger_log/marpa?date=2023-10-26#l12

[jeffreykegler]

How is this coming? Based on Choroba's Helsinki talk, I plan to add a couple of new FAQ Q's.

[ronsavage]

Hi Jeffrey

All work was finished at that time, as far as I can remember. The last push was to the dev branch, which is now 46 commits ahead of master.

The online version uses the new numbering system, so you are good to go.

-- Cheers, Ron

savage.net.au

[ronsavage]

Hi Jeffrey

Also note specifically note # 12 in guide/faq.format.txt, which discusses the fact section numbers are either fabricated or renumbered each time scripts/preprocess.pl is run.

I've manually tested adding new questions and even sections, and the renumbering worked.

So - go for it!

Let me know if you want to run preprocess.pl yourself or if you want me to run it. The latter is fine by me. I need to refresh my practice anyway. -- Cheers, Ron

savage.net.au

[jeffreykegler]

Just looked at it and all seems fine. Does anything remain to do before closing this issue?

[ronsavage]

Hi Jeffrey

All looks finished to me. Plz close. -- Cheers, Ron

savage.net.au