Guide Tour/Combinators example use sqrt word without mentioning USE: math.functions

[pierre-rouleau]

The Factor Handbook / Guided tour of Factor / Combinators documentation page has an (executable) example about using the sqrt word (currently at line 284 of the basic/help/tour/tour.factor)

The example fails to mention that the math.functions vocabulary must first be installed with USE:.

Being able to use docs in Factor itself is quite nice. I think I could add the extra text, but I'm unsure about the overall documentation strategy for the tour:

• Should all examples be executable? I'd guess they should be, given the fact that you can simply press on the highlighted example show in the Listener help window.
• Is there a convention in introducing a required vocabulary in the tour?

[mrjbq7]

Does it not prompt an restart with USE: as an option?

…

On Tue, Jan 9, 2024 at 8:42 PM Pierre Rouleau ***@***.***> wrote: The Factor Handbook / Guided tour of Factor / Combinators documentation page <https://docs.factorcode.org/content/article-tour-combinators.html> has an (executable) example about using the sqrt word (currently at line 284 of the basic/help/tour/tour.factor <https://github.com/factor/factor/blob/master/basis/help/tour/tour.factor#L284> ) The example fails to mention that the math.functions vocabulary must first be installed with USE:. Being able to use docs in Factor itself is quite nice. I think I could add the extra text, but not sure about the overall documentation strategy for the tour: - Should all examples be executable? I'd guess they should be, given the fact that you can simply press on the highlighted example show in the Listener help window. - Is there a convention in introducing a required vocabulary in the tour? — Reply to this email directly, view it on GitHub <#2932>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAF5A243PA2UMCYMQ3WGO3YNYL2PAVCNFSM6AAAAABBUE7BDSVHI2DSMVQWIX3LMV43ASLTON2WKOZSGA3TGNJXGM3DQNA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[pierre-rouleau]

The error handling pop-up does, yes. Is this the reason you don't mention it in the tour?

[mrjbq7]

It's partly why it's not always noticed -- some of the tour has for example USE: ranges blocks, that then make the following code example work immediately. But without that, the restart is a convenient way to allow the user to pick the correct dependency and then continue.

PRs welcome!

[razetime]

in such small snippets i didn't think it would make sense to add a USE: in the snippet. One idea is we can add a note early on in the tour talking about missing vocab errors.

[pierre-rouleau]

I agree with @razetime, and I would also think that a note describing the error handling, the pop-up window and the suggestion that comes up whenever a vocabulary is required and has not yet been loaded would help and be sufficient.