#41

ah yup, I think I did this (though I remember running through some failures, do not remember what they were now)

brew install python3
brew install pandoc
brew cask install mactex  # warning, MacTex is a very large install!
cd utils
pip3 install -r requirements.pip
#42

holy smokes. my rural internet doesn’t do well with these modern times. thanks for the confirmation.

#43

I feel your pain, sincerely.

#44

primarily proofreading and spotting formatting issues right now. i’ll post my findings here as they come, in case anyone has bandwidth to start hacking formatting issues (otherwise i’ll start on the list once i finish proofing)

first one:

code blocks indenting all lines after the first line:

02 AM

#45

ok, proofing done-- looks great. only a few minor edits though there is some content to be flushed out.

regarding the code block bug, i’m struggling to figure it out. it’s not a style issue-- the indention is in the html, which makes it seem like a markdown to html problem with the packages themselves?

#46

nice that there wasn’t too many issues! content-wise, I put some suggestions in the initial post, if you’d like to add any of those feel free.

I’ll take a look at these code blocks real quick and report back.

#47

re: code blocks

hmm, so the html/css side of things looks correct, and based on what I’m seeing in the ops files and glancing through the pandoc docs on indented code blocks (which albeit is pretty dense), it doesn’t seem like we are doing anything weird in our docs.py config that would lead to this hanging indent-ish style. cc @sam, curious if you can spot what might be going weird there.

#48

wonderful!

right now i’m adding the JF ops and then i’ll tick off your suggestions in the first post (which i’d forgotten about, thank you for the reminder and great roadmap)

1 Like
#49

This will be why…

                <pre><code>P.I 0
                P.START 0
                P.I 1
                P.START 10</code></pre>

The HTML has been beautified… just trying to figure out why…

#50

@Galapagoose

i’m correct that JF.NOTE and JF.VOX are modal? so there are two descriptions for them? this breaks the doc lookup table so i’ll need to inline both mode descriptions in within one entry in the op table.

#51

Seems to not have a problem with this commit:

…

…

Fixed…

diff --git a/utils/templates/template.html5 b/utils/templates/template.html5
index 32daa79..58d9b18 100644
--- a/utils/templates/template.html5
+++ b/utils/templates/template.html5
@@ -132,7 +132,7 @@
         </script>
         <div class="content">
             <div class="content-inner">
-                $body$
+$body$
 
                 $for(include-after)$
                     $include-after$

Just need to unindent $body, possibly it needs to be done elsewhere too. Can I leave this with you @jlmitch5?

(For reference you can see the default pandoc HTML5 template here.)

1 Like
#52

i’d like to scrap the “what’s new” section and instead have the top be:

  • current version
  • link to how to update
  • link to changelog

and then make the changelog more verbose, ie, say what keybindings changed.

@jlmitch5 @sam i got it, if you don’t first. i can roll it into this PR i’m building. this fixed it, thanks!

#53

ah good call! I did that indentation to make that file more readable, but the issue now makes sense.

@tehn happy to tackle it in a couple hours, but you are welcome to clean up! I believe that $body is the only place generating white-space: pre content, so I’m assuming it’s probably the only thing that needs to be de-indented.

#54

That sounds good. I’d say another important thing to get in there is a link to the teletype studies. My logic is that the intro should be:

  1. for people coming to the teletype module for the first time to understand where they can go to learn more and start to have a better understanding for what it’s about.
  2. for people who have a teletype to be able to easily access as many resources as they can for using and learning more about it.
3 Likes
#55

In general I wrote so much of the content and the structure of the docs in such a hurry that I didn’t really give a huge amount of thought to it, I was mainly concerned with getting the information out of my brain. So please reorganise away…

Nonetheless, I think the “what’s new” content serves as a much higher level overview than the change log, which is more of a developer log than anything else.

It’s important that users upgrading to a newer version can see what the ‘big ticket’ changes are. The features to get excited about, the ones that might change the way they think about a composition.

So wherever it ends up, I would like to try to keep those aspects of the “what’s new”, and to make sure that it’s prominent.

2 Likes
#56

i see what you’re saying and i agree. i think i’ll move the “breaking changes” portion down to the bottom of the what’s new section, so it’s not the first thing a user reads.

1 Like
#57

ok, i’ve pushed a minor update to the docs (apologies for not submitting a proper PR, i’ll do that next time).

i’m having a much more difficult time than expected reconciling the existing docs and this new doc. i feel that monome.org/doc/modular/teletype should remain some sort of landing page with the basics: description, media, etc. this page functions as a introductory lesson as well, whereas the 2.0 docs tend to be more of a reference guide. but perhaps with the tt tutorials, the introductory lesson on the current docs page isn’t needed?

perhaps it should be formatted thus:

  • intro page, with description, media, installation, and then links to tutorials and reference
  • tutorials (as-is)
  • reference (the new 2.0 docs)

secondary are the command reference and key reference. can these be easily extracted as separate files from the 2.0 doc system?

1 Like
#58

I’m not sure if you mean reconciling from a technical standpoint or from a content standpoint. If it’s the former and I can help in some way, I’m happy to take a look (not as familiar with the hosting situation of the docs but could look into it).

If it’s more of a content thing, I think it is totally cool to have the current page stay up and be the landing or “marketing” page.

I think I’d prefer that the more descriptive mode stuff (and possibly some of the other stuff below), be consolidated within the in-the-repo documentation and removed from the landing page. As an example/reference point, I personally think Olivier/@papernoise did a good job separating what to put on the main module pages and what to put within docs.

1 Like
#59

and not super sure on this one, but I don’t think it’d be too terribly difficult. You can see in the docs.py file, that the output variable that gets concatenated is eventually passed to the pypandoc.convert_text function. I would probably just try to concat the relevant paths to a different commandAndKeyOutput variable, and then call pyandoc.convert_text with that. If you don’t want the custom html template, I think you’d just not pass that argument to pypandoc.

1 Like
#60

content issue, not technical. thanks for the tip, i’ll check out the mutable docs!

i agree with you re: removing the bottom portion of the current landing page-- i did a bad job explaining that in my proposal, apologies. basically it seems that everything after COMMAND SET should go (as this is the reference) and the introductory notes before this remain useful though they need to be updated for accuracy (ie keystrokes).

1 Like