Sublime Text Live Coding: [LC24] Enhanced Help Authoring

Sublime Text Live Coding: [LC24] Enhanced Help Authoring



all right I think we should be ready to rock and roll equipment I don't like it that's not true I like equipment hello fellow sublime text fanatics odet nerd here welcome to tonight's livestream the last one of March I'm torn between thinking that the stream shouldn't go as long as it normally does because I have a lot of housekeeping of a digital nature to do for some stuff that's happening tomorrow and wanting to go all night and into tomorrow because April Fool's Day is sometimes a bad day to be on the Internet but what are you gonna do push f12 I suppose so here's the deal the plan tonight is to work on some hyper help author type action and to be honest I had a very busy week doing all sorts of things of a video recording and video editing nature which includes things like discovering that apparently the mini port the mini displayport mini port the external adapter connector holy jiggy on my laptop maybe on the way out because while I was doing some video editing it kept deciding that it wasn't connected and then after that that problem went away it decided it was connected but no signal was going across that's not really the sort of thing you want to have happen especially when the emergency backup is to use HDMI which only one of the three monitors on my desks currently supports because the HDMI czar being used by other machines and it's the monitor that has the most stuff around it and is the most precariously placed with regards to having to have everything on the desk move and it's impossible to plug an HDMI cable in blind in the middle of a bunch of other cabling it was not fun it ended up working though in any case I said we do have some ideas of things to work on for tonight and we are focusing on a hyper help author the authoring tools for hyper help if you've followed my live streams you've probably seen those us working on it before in particular the linter type action so these are the sort of the five things that I've come up with as things that we could sort of work on and the first one of these is the one I want to work on first and as you can see I was such in uh-oh I don't even need to do that I'm I'm well off the rails here I was in such a hurry to get this stuff all settled away that I didn't actually type out any of the normal description text that I would put on these things to explain what they're doing before that actually I think we need to try something else out here first okay well let's just let's go about this in this way I should I can't remember if I welcomed you to the stream I'm pretty sure I did we're working on hyper help author I'm pretty sure I said that subscribe to the channel for live streams blah blah blah I have another channel look down then the thing below I make videos there subscribed yada yada good news if you are watching this live stream right now live you are hearing this now video is going live on the channel tomorrow to coincide with my telling people that snappy exists officially so people other than us are going to be able to know that this package exists and sorry is getting weird overlays on my obscene that's making me think that things are all weird but stream seems to be doing what I would expect it to do so good so I'm gonna be doing a I would say a release tomorrow but I'm not really doing a release tomorrow with these packages they're just gonna be mentioned in the forum for people to look at there's gonna be a video that talks about snappy and how to use it so that's pretty exciting nobody else knows about that it's gonna be an April first thing no one's gonna believe it it's gonna be great that's my way of shielding myself in case people decide that this package isn't very good in a while I was making those videos I needed to create a video not only for snappy but for Hyper help and also for Hyper help author and lo and behold I discovered a bug well I didn't really discover the bug so much as I knew the problem was there because it was on my to-do list but I just never authored help on Windows and the issue there is that hyper helped author needs to for open files determine where those might exist in packages that's so that it knows to reload what file it's but package the help is related to and stuff there's two problems with that one is Windows uses a different path separator than Linux does so various things went horribly awry in that case and also the authoring tools were originally authored back when one package one help index was the rule and now the rule is there can be as many indexes as you want as long as they all have different document routes so a lot of things incorrectly infer what package a file is related to by using the actual package part of its package name instead of looking up its path so we need to fix those two things should we have that done in no time we can go on to opening help from packaged files because right now now I'm not entirely sure I think loading a help file like this might actually work I'm not 100% sure because I can't remember if I'm actually doing an open file or not if I am they might need more work to come out of a packaged file instead of a regular file and even if it does open it's certainly gonna have problems trying to save the file cuz if it opens from a package it'll be read-only so we need to add extra stuff to do what package resource viewer does and in that case make sure that we can create the appropriate directory and save the file and make it an odd read-only and stuff like that other things I discovered and maybe we might even skip down to these one of the things that the Lindt doesn't warn you about is that if you have a help file that's not linked anywhere in the table of contents and an extension of that which may or may not be related is telling you when a help file isn't linked anywhere because the part of last week's run up to stuff or the week before as I can't remember now it's been a blur of activity I guess the week before cuz this last week I've been doing a lot of video editing and proofing and re editing and things like that is that it's all well and good when you're working on your help to have your help files like colors and customization and example and all of this stuff but if you forget to create a link to it and don't want to ever see it especially if it's not in the table of contents so I think some sort of warning to tell you that not necessarily that the file it's isn't linked but maybe do some sort of check where you have a list of all of the help files and every time you validate a link to a help file you add what helped that help file to a set and at the end if there's any things and one that aren't in the other we know that file isn't linked anywhere from any file that help file is just orphaned per se I mean it might not be if it's lengthen the table of contents I want that to be a warning and not an error because it is entirely possible you might have help that's not linked if it was like context-sensitive for example if you were a packaged author and you wanted to say like in my override packaged report I want to be able to display some very specific help when you press this key but it's not something you need to see in the general course of things so we want that and also and this is I don't know how super exciting that is except I would find it useful from time to time because I don't have a keyboard shortcut set up to pinging that to pull the lint panel open but the same way that finding files can shoot stuff into a buffer it'd be nice if the lint output could do the same thing I'm not sure how we I mean I know how it's easy to do that if I just create if I say window dot new file instead of window dot create output panel that'll work but I'm not sure how the the finding files handles the case where it because you can double click on things in the lint panel and get it to jump to the appropriate locale so there's that but there is something else here to note and this is gonna be one of those what I'd like to say watch this a moment's because something is probably going to go terrible I'm on dev Channel build 3202 here as you can see I'm gonna quit something I've been working on recently is this new script st tool if you watch previous live streams way back when I had an ST 3 deploy sandbox script where you could provide it a build number and it would cantar that i've enhanced this to the enth degree so if i do this i can see that the latest stable version is 3200 and the latest dev version is 3200 3 which is not the version I have I have 3202 so if I ran it without arguments we can see there are various operations you can provide you can get it to create a sandbox which is the default operation you have to specify a build number and you can also see that what the latest version is and do what I cut I'm calling and install which is the thing that I'm going to do here we're gonna see how well this works if I st tool and say i want to install build 3203 here's what should happen i don't have this build locally as a matter of fact let's test that first if i said check for build 3203 oh it does think i have it huh may i downloaded it but didn't install it well that's a bummer anyway I want to install build 3203 it doesn't like that huh whatever oh I forgot the minus B you know I not really a super fan of that argument structure but it's written as a bash script self did you do now it's deployed the sandbox extracting okay that let's see how well that worked hey look at that 27th of March further improvements oh yeah oh right I'm gonna quit and restart cuz it told me to I always do what I'm told so basically what this was doing is it can do the sandbox as it always you know could before which is the default sandbox is a certain build but the directory with a name and if you specify – and it doesn't put the data directory inside of it so that's what this was doing but because I used install it put it in the directory where I normally install things and then the last thing it did was swap the sim link because as I believe I may have showed previous if I did this I have a redonkulous number of I got a spare file there even a redonkulous number of builds here and for any particular one I just Cymbeline sublime text 3 – the one I want to work with that allows me to very easily swivel swab all through versions well I mean it's easy now because if you tell it to install like this it'll just automatically flip the link to the one that it needs if that folder doesn't already exist but the previous they used to have to do that manually ok so that's cool now we're on the latest and greatest of this and one of the reasons that I might have to call the stream early unless I get caught in some really exciting type action here is that I still have a little bit of work to do I want to push out one last release of snappy tonight before the forum announcement tomorrow because I noticed some stuff like for example the bottom of this help says API help copyright sublime HQ Pty Limited because I do not have a copyright on the help as a matter of fact I mentioned this a ways back in the discord and will seem to think that they had the copyright but if we were just using it to show to people John was unlikely to care the thought occurred while I was walking this morning that I should probably ask but I can always make the package the repository private but in any case if we looked at for example sublime build it also says API help because I just utilized that I don't think they should say API help it should maybe say build help I think it should say sublime text help copyright blog because and then all of them so I'm going to need to change that as we can see there's also a change in the because I boned up find/replace ways back so there's that as well so we'll see what happens but anyway as I pointed out in other we're in the first thing we want to work on his commands need to use local path separators and I did create sort of a fix for this just to be able to create the video I was working on but it is by no means stop doing that there we go I want to look at this one for right now and another thing that I didn't even put in there is there could be a lot of cleanup type stuff happening in this thing let's look here first zoom that out hi help setting is authoring hmm package for view local help file name determine what the full file name of a help file from a given package would be if it was stored locally this is something that I want to check and to do this to create some stuff just to see there is if you remember if you follow the forum for sublime text Oh in a second there if you follow the form for sublime text I'm gonna turn a fan on here because it's a little warming here right now actually maybe I could actually open the window a little bit yeah well hang on that for a second – what does sublime when sublime text 3200 was released the official sublime text 3 point – sublime ripple was broken and specifically certain aspects of it didn't work and other parts did work I looked into that a little bit for John in the because P I kept seeing people asking it all over the forum and on Stack Overflow and on Reddit even and the ultimate determination that I made was that there John says that there was a regression in the API I don't think so I think it finally started enforcing something and hang on a second I got something going on the other on another desktop here and it was complaining about stuff there was the all packaged resources should always be in this format that is with the forward path separator as what I would call POSIX pass the paths that are native on Linux and the paths that are native on Mac OS and even on Windows this is how packaged resources are supposed to work however sublime repple does something very similar to this it joins packages paths with parts of a file and the result of doing that was a file name that's sort of local sorry in this particular it's not doing this specifically this is something I want to check but it would take the filename of a path throw off you know the part that wasn't the packages path to just get you know packages slash user slash something and then try to use that as a resource to use sublime download resource and that fails in spectacular fashion because it has the wrong path separators previous builds of sublime text that would apparently work the most recent builds it's they've put it back that way but for that one build it was broken and it was really it was broken because of sublimer Apple was doing something wrong but it just so happened if the system was masking the air and I want to make sure I'm not doing anything like that in anywhere and here where I'm working on stuff from hyper oops help core dot core import help index list that's a thing I can do right and then I can say x equals health index list for let's say my user package because that's one that's definitely going to be everywhere and if I run that command and type X I get a whole crap ton of stuff right so if I said X dot doc root like this and it's not a method I'd see user help so if I also import OS top half or just OS and say OS path join sublime dot packages path which is going to be something at a POSIX path with X dot doc root and index dot txt I end up with a file name that looks like that okay now and this is where things get quote-unquote interesting this is a chrome remote desktop for a very slow but usable HP stream that I have actually sitting to the desk on my right it's not nearly powerful enough to be able to live stream anything even if that was a good idea now I suppose what I should do is copy this cuz a snappy should be and hyper help course should be installed on that ah crap we go put that over there for a second I might have to do this just for now now that we know that that window was there because I need to be able to interact with it normally I hide windows that I'm not going to fiddle around with so that they don't clutter things up I don't think I can roll this up can I know so in this if I ran that code and it's kind of irritating that it's gonna keep telling me that I might have to actually make this window not be maximized so that I can whoops do that if that's going to constantly display there I believe is a security issue you know what I'm it's really hard to do that using the mouse that's attached to your that on this line X machine so I'm just gonna turn around and grab it with the real mouse it's easier that way okay so I pasted that in so I could now again say X dot doc root and what we're gonna see is still that kind of path so that's good so if I said OS path join and I'm thinking this is where it's going to go wrong sublime dot packages path X dot doc root and index dot txt well if I imported OS first and then did that see I end up with this bizarre the path isn't as it should be so to say now this is the magic of yeah we actually want 3.3 for this I would imagine because I think there's something in here that we could use to I'll fix a path norm path yeah I think that's the one I'm looking for normalize the path name by collapsing redundant separators and up references say because the string manipulation may change the meaning of a path that contains symbolic links it converts forward slashes to backward slashes to normalize case use norm case alright so that might be something cool for us to do here oh I did that wrong didn't I I need the path in there I've got my mind on all the stuff and to be doing later on that seems to have resolved that so we could say if I also tested such thing here where's the thing I just did the love of Pete man OS path norm path that still works the same so if we wanted to know what the full file name of a help file from a given package would be if it was stored locally this should actually be OS path norm path although that does beg the question that we need to make sure that anywhere that this is invoked is actually something that you know works and is it could handle that such a path open local help attempt to open okay now we get the local file name and we say window open file so will this it's conceivable that this might actually have been broken and build 3200 on Windows because unless unless this doesn't have the same path type handling but I expect a local path to work so I think that call should be okay and if we wanted to open an index I think we need to do the same thing here the index file is stored is a reference file spec so strip the prefix this might actually be wrong join the packages path with the index file okay let's check what index file returns it gives you a whole thing inside of packages so ok I'm imagining if I stick this on that is the magic of the string slice that throws the packages part off yeah so that I think should work but we still want to say Oh s-stop half ton norm path on it space that out the idea there being this this doing that what this thing we just looked at was doing was figuring out what path did I have that on multiple lines here I did let's do that here too since we're doing it there looks a little nicer perhaps this is figuring out they'll help for a local file or the local file name for a help file by taking the packages path adding the document route and adding the help file and then normalizing the path because at the very least the package info doc routes always going to be in sublime resource format and not local path and we want to make sure that that's just consistent for some reason I do sited that I didn't need to do that for indexes but it really seems like it probably would have been a good idea so I might actually just boost that up but we want to do the same thing they're only here the index file includes the packages thing here which is just to make it easier to reload the index you can just use that to do the thing just checking YouTube telling me that I'm currently alive so that's candy so we have to throw that packages part off because this is going to include it and if it doesn't exist help index doesn't exist otherwise it says open the file now I think this is where that open help from packaged files is it actually tests to see if a local file exists so yeah that's not going to work for the same reason that's not going to work either but at least I put in ascending to indicate that that was the case all right here's what we're gonna do here cuz it's gonna it's gonna bother me Oh to dev local help index package info I don't think we even need just returned that determine what the full file name of a help index file for of the help index file for the given package would be if it was stored locally and then reflow those at a period because we're a stickler remove an extra line copy that come on down here and local path is such that probably still works then it complains and apply authoring settings so just to test all that business package reloaded so that's good if I said no I guess I should probably verify where these things are actually called right okay open local help referenced in 230 when you say edit help which is what I would have expected so we can do that there and open help index is coming from 390 which does the same thing so that means if I said edit this help file that's where that code comes from and it looks like it opened it and if I said edit this help index it would also open that so it looks like that still works just because I don't think I've ever actually mentioned this previously anywhere as a matter of fact it occurs to me I also edited the I just finished did editing and uploading the final version of the hyper help authoring tools walkthrough video for people who want to create help that video is not going to come out tomorrow that video is gonna come out in a couple of weeks I'm doing a three week rolling thing so I can use these next week's to create more videos and get myself a little ahead of the curve but you'll notice here if I went up to tools and said hyper helped author oops that's over I taught it to do edit help index dot dot dot when I pick it it automatically opens the index for sublime bill because that's the help file that's open right here if I did it over here instead in this window and said hyper help author and it help index it asks me for a help package first and then it does it similarly if I was over here and I said tools hyper help author and it help file it's showing me the files inside of this build package for the file I want to edit like say I typed index tough texts and got to open the index for the build system over here in this window if I say tools hyper help author these and it help file it asks me what package I want to do something in say Co scheme and then it asks me what file I want to do something with say index and it opens that one and it should be fairly obvious the different the thing that's making that happen is that this window has a package a help package open in the help view and so it can it automatically infers if you want to edit a help index you want to edit the help index for the help you're currently looking at and if you want to edit a help file you can do so by you probably want to do one in the current package another thing I am probably works if I said hyper help author and help file the package it has to ask me for a package there too so anything that requires a package argument these commands infer the one that's it and using the current help package if there is one and similarly while I'm here we're gonna edit this help file because I don't like these characters they are the characters that are actually in the actually I should copy that one first and then do that those are the characters that are actually in the of any more of them one more oh that's in the actual help file I'm looking at right now I would imagine yeah fix that by reloading the file those are the files keep getting distracted by while I'm talking those characters were actually what's used in the help file so that's why I put why I put them here in this but in some fonts that character is a different width than other characters and it was disturbing my delicate sensibilities because the build systems have tables in them so anyway getting back to what I was saying before I got horribly distracted by that any hyper helped author command that requires a package will infer the one from the current help view and anything that requires a file well most things that fir and for a file automatically just use the one that's in the help view except for the one where you want to edit a help file it probably doesn't do wanna you know worry about that if you pick it that way versus this way so that's the code in common probably fixed up for what we have in here including having a new thing this is the thing that's excuse me sets the appropriate author settings in which is something that I'm pondering maybe this needs to be backwards instead of forwards right now hyper help author has its own custom specific syntax specific settings for help files to ensure that they display like this no rulers fold only on hover other instances of the same word aren't immediately highlighted like they are here because that all that gets in the way of looking at the help so that's what the default is when they pop here and when you pick edit it applies the settings that you told it to apply for authoring instead what it could actually do instead now that I'm thinking about it more is make you specify settings that you want to have edit for edits inside your own stuff and it could actually when it displays the help go out of its way to remove those settings I'm not sure how deep a code change that would be which is why I haven't done it up till now I don't want to rewrite the core again at least not right away because I just finished one so we don't care about that now let's look at events see what's in here before we're gonna save apply the author settings I wonder why it does oh I see that system up here excuse me I thought it was I thought it was that other one applies a setting that says that this is the hyper help authoring type thing this view has the setting that indicates this is an authoring view that was just opened or created remove the setting and apply the authoring settings to it yeah so uh unload we do that so that we can do magic stuffs because otherwise there's no good way to do that so on load if the views to help file that's mark is being opened by the authoring tool the authoring tool does that on its own to make those settings go that's another reason why that's terrible so to say is a potential code change especially this close to having someone who's not me look at the thing okay so that's events we already did something in common so we really got to look at this giant pile of stuff look this out the code in help index dot pi which is actually in the hyper help core use this POSIX path is the path module instead of OS path because in packages all files are POSIX there's probably going to be interplay with that in this code in an unfortunate way since it needs to work with local files and match them to resources I'm gonna go out on a limb and say boy howdy did that happen so this is the one that did something funky right let's see what happens if I do this oh right sorry it's not POSIX path that path POSIX path is the replacement of OS top path or if you will there's a POSIX path in nt path and maybe another one and the underlying OS module substitutes the appropriate one for OS path when it starts up that still seems to do dumb stuff it's actually dumber than it was before cuz of that so we'll see what we think about that per se to do let's go back to here so that's maybe go through a help header focusing on the date field because we do need to be able to update a header and this might actually be something that could be done smarter now cuz help files have us a very specific scope I think edit this help file and see I don't know that the key and value texts hyper help help it doesn't have a metal line alright so that's something that could happen but it doesn't right now if there was an official scope on the contents of the date key this wouldn't have to try and reparse the thing which is probably something that's going to cause a problem there's a lot of work that needs to be done in hyper help author all this code was originally written back in December of 2017 is my dev ember project when I rewrote hyper help from the ground up as part of my develop reject that year because I decided that it was one of those things where I started the package as just being for override audit and had just the features I needed for that and then as I worked on it more and realized I could use it for more stuff it expanded to a point where I was really fighting against my initial design to make things work so I spent that to member project rewriting the code in the project to work the way that you know it to make all of those changes easier if you will the the new logical core this is an important rule to take away if you're a software developer and you're if you're new to software development it's not unheard of to throw a whole codebase away and start fresh certainly it's not something you want to do lightly because programming is a lot of work and you if you don't have to do something like that then you shouldn't do something like that but what I had was a real hodgepodge of stuff like you know literally there were there were two different ways to create anchors because I was trying to make it look the way vim help works and there was you know it couldn't even you couldn't link to things outside of the current file originally and then that sort of started to be something that needed to have happening and I I kept adding on to the design and it became clear that I was sort of fighting against what I had originally designed it to work for to do designed it to do to do the stuff I wanted so it really was a good idea to just restart it in this case don't be afraid to do that but also you know don't spend every Monday restarting all of your projects you really need to give a lot of thought to how you want your project to work when you start to make sure that this sort of thing doesn't happen and in my defense I didn't really much like override audit itself all my package development is things that I myself want to use and if there is something that already exists on package control then all the good for that that's why I never wrote you know anything like package resource viewer although there are plans to add functionality like that to override audits just to round it out its functionality for working with overrides might as well create him as well as being able to find them and clean them up but if there isn't something like that I am in the unique position as a software developer to just create my own so that's why I created override on it and that's why I created the help system and thank Keith Hall who's known as King Keith on stack overflow in the sublime form and the discord actually on discord I think he's just known as Keith if I had to guess we refer to him as your royal highness for convincing me that people other than me might find it useful which might have just been him but nevertheless so things change let's go through this this might be the best part of this dream is this me reacquainting myself with how this thing was supposed to work yield a list of packages sublime currently knows about those that have at least one resource and are not ignored optionally filtering away packages that have helped indexes to find currently the list is yielded in package load order okay now this is the thing where if I was to say add help to package it shows me a list of all packages that exist that don't already have a help package that's why it user doesn't appear in here because I have one now I'm getting some weird scratchiness here hang on a second my apologies that I'm not sure if that's coming through the headset or not but part of my bump I think I moved the boom but I'm hearing a weird scratching as the headset cable rubs on my shirt so this is the thing that's doing that and it's doing it by finding all of the resources find every possible resource and if it starts with packages split the package name off now we have seen in other streams that the contents of the cache folder pop up here too which is why it does that once it's done it finds a list of all of the packages that exist in help index list and removes those out and what you end up with is a list of all packages and then this is an iterator if you want to actually filter I should say that it doesn't have to do that but you almost always want to for this stuff I think if default is in the set it should come out first cuz default is always the first package and if user is in there it should come out last otherwise it pulls out items that are sorted but don't have those two packages in them this is so that it yields the packages in the same order that sublime would load them now normally we would say possibly a problem here because there's not a real correlation between the actual physical package and the package that the help is stored in for example snappy itself has three different indexes one for API help one for built up and one for color scheme help all of them still appear in the package snappy so it would actually be interesting to see whoops that's not the key I meant to press snappy shows up in this list because it doesn't have it's a package that has exists but it doesn't have an index associated with it technically that's not a problem there could actually be a snappy help system that tells you how to use the snappy help package so that's cool it could theoretically be a problem but since the general use case is that someone with a package would add help to that package as opposed to what snappy is doing having multiple packages built-in that our logical packages that don't match the physical package I think this is in fact redacting the things that we want it to now this is something that could be very heavily repaired this is the sample index that gets generated when you create a new empty index it should really pull this out of a resource instead of doing this but this was most expedient at the time I believe I spent a lot of time realizing you got to double up these braces because the otherwise no they're considered special writes it as utf-8 may crude help does the same thing for an index file it writes out a stub root help file but Boop with the appropriate just something in it so this command is for updating the header command let's see it gets the current date in the format that we need for the header and then it checks line zero and parses it that could actually be something that happens inside of snappy maybe we don't even need to do this sorry the inside of the core I'm not sure if there's actually that's actually exposed as part of the API let's investigate that I do like I said I do have you know these lists of things that we want to do but I didn't go over any of them I didn't in my walk this morning I didn't try to plan out what I was going to do because I'm really just not familiar enough with this code to really make any sort of determination so the one thing I knew I needed to fix is the path thing which when we get to that command I'll fix it there because this package as it currently exists unless I committed that change after I ran out of proper and it's of problems keep doing that so that I can see stuff happening I should just for temporaries sake I'm gonna bring this window back over to this zone so it's not here because the chrome remote desktop wants to keep timing it out and it's a pain in the butt to get it to connect again because I'm using a different account then I would normally be using for something like that but I ran into a bug with the hyper helped author while I was doing the video and patched it so that I could continue recording but I don't know if I actually pushed it anywhere so if we looked at close up snappy and open the core and I'm not actually sure where exactly this might be not open local help show health topic if we found show help topic it looks up the topic opens new tab if it needs away attempt to display the help in the given package to do transparently creates the help view so existing view is true a find help view is none then we called this so if we call display help file it calls this I'll actually own this you probably didn't want to do that probably want to go back to their actually one of the things that happens after help is loaded is it runs that post processing right can Prost process post process header command processed the header and a newly loaded help file parse help headers I think this might be something interesting you still need to grab the first line and it needs to know what the help file is named that didn't help let's go back to there this thing whoops sit in that one an internal help command the definition is in the core there it is I knew it was in there somewhere just close those two for the time being so we don't get too confused give them the first line of a help file check to see if it looks like a help source file and see this has header prefix it finds the title that finds the date and it returns something it needs that help it doesn't really need a help file so if we looked at this I'm going to print that and in order to test this we need to edit this help file every time I push save we should see it saying that right now the message is it's already current well you can actually I again I don't know if I ever pointed this out now don't do it that way I'll do it from the menu here although that command triggers every time you save the file you can also update help file header and it all say that help file date header is already current so did you do match expand oh I guess it's some level that needs to do that no needs to match it because we need to be able to recreate it and just change it so let's say we don't want to do that here that call I was just looking at we do want to pull it out ourselves because we we want to leave this title this line exactly identical except just to that line changes which I'm kind of surprised it's not reporting that there's a changed era to be perfectly honest but that's neither here nor there so if I like decided I wanted this and this said it was the 30th it should leave that space there let's revert that which is that's why it's doing it this way I'm gonna say sweep that's probably okay next create help command this is where we get the package which is the one that's given or the current help package for the window and prompt if there isn't one if there isn't help for that say you can't do it otherwise create the file and oh that's because you can invoke the hyper helped author create help command with a package and a file and immediately just go you can also set prompt to be true when you call this it defaults to false if you want to create a key binding or a command paddle entry or a menu always prompt you which is not what these built-in commands do because I find this way more helpful than that way in a second I need to find a nail clipper because I have a terrible hanging here there we go create file we get the help index list for the package local help file name ok so this only works for help files that already exist so it gets the package info for the current package gets what the local file name would be for a file of that type make any directories that need to exist if they're not already there good to know create the file these this sets the setting to know that we're authoring it when it's created so that event handler knows to apply settings we set the default directory to the path that the file is in so that when you try to save it automatically saves there we set the default filename apply the appropriate settings and here's the snippet that's used so that seems like it's probably cool and it and it help command should be similar get the package get the file it gets a list of all of the things that it could be do you doing which is the name of the file and the you know oh the key is that the key is the file and that the value is the name of the page that's why if we say tools hyper help author edit help file no it's gonna do it that way is it no that's neat that's how it's gonna do I could just pick it from here right no no it's not in there shoot – looks I just stopped doing it that way do it this way we get the name of the file on the page title one of the one of the other places that titles are used okay then if you actually gave a file it tries to open the file and otherwise it waits for you to pick one and then calls that thing that it would have done to open the local help file so that's probably cool create index that asks you for the document route defaulting to help when you finish selecting it it calls create index which makes the document route which we're gonna see down there in a minute I would imagine and then creates with path joined okay so that make document route it's a local path so that should be okay and create the two appropriate files complain if the index exists or the root file exists so we don't clobber it then try making the appropriate directory if it doesn't already exist this covers not only things like if you pick a package it already exists and you specify a document root that doesn't exist it can create it but also if you try to create help for the default package it'll create the packages directory default for you so that it can put the document root inside of it which is why that's makers and it's okay if it exists you know to complain it makes the index it makes the help file which we just looked at it creates a resource and tells packet and we actually manually load it that's right now there are issues when you create new resource files in a package from within a command the sublime has to get out of handling your command and any commands that it invokes and go back to the main loop in order to synchronize with whatever background process is responsible for looking up new packaged resources because there's you know file scans happening in a background thread until that rendezvous happens and it could be any number of seconds afterwards depending on machine loaded and stuff resources that you have added sublime doesn't know about because when you call sublime find resource it doesn't do a scan right there it's just giving you information that it previously calculated it's like coffee break so in that case until it's managed to update that list because it was told by something else did it it's not gonna report that which means if you drop it help index and immediately try to reload it it kicks you in the head because it doesn't know about it so after we make the help index we create our own help resource file and load it the load help index knows that if it tries to load load this and it doesn't work to fall back to actually opening the file manually and loading it that way and if it gets something it manually injects it into the list for the current package which makes it appear to be loaded as a matter of fact that doesn't even display a message in the console which may or may not be a problem something for us to work on later and then it tells you this and one problem that I'm having with this from a visual perspective is if it ends up with double slashes there because the document root has a slash on it always I think the file names are definitely always the same okay join paths dock root and that no because we'd have to use POSIX path or it'll end up the wrong way I'm gonna leave that for now because we need to investigate what dock root does does it ensure that it always ends in a slash as a matter of fact maybe we could actually do that right now if I did look for load help index pops the value if it's not already there if there isn't one then it pulls one from the name of the resource huh I'm not a hundred percent sure that that's actually oh no that's right yeah it needs its relative to the package it's stored and even if it's not the logical package yes so it takes packages /off so it splits the path okay so I think we would need to know we already have OS right so if we said OS path split packages slash user slash help like so the first item in that list is that the one that was looking at there with packages removed would just be user otherwise it's normalized the containing package and that so does this I don't think it does okay so the reason it it displays that way and then we're gonna go ahead and test that in just a second here everything to do with the document root that's specified so if I said I did this and then I said and help to package and picked I'm not gonna find it doesn't have any resources in it oh that's a potential issue that might not have been the best way to figure that out the only other way to do that is more unfortunate luck that is a defect so if I specify it with help with a slash on it it says it created them for the package and notice that it has double slashes there I'm gonna cancel that and whoops that one I'm going to remove help now I think I need to quit and restart sublime in order to get that to do what I want it to now if I did that again and helped to package and I picked a sample package and this time I picked help with no slash I'm able to create the document root index file okay so that part definitely needs to make sure that it's on there that's good to know let's let's start adding notes for stuff that's broken here this is from the core right yeah so let's get rid of that let's say if we follow this to create a new empty help system it's gonna come back to the part where it calls create index which is here root path is make document root package doc root and okay root path was none it can just all because that would have showed an error I suppose how come adding index path to that causes a problem what error message did we see Oh unable to load resource not found because it doesn't have the slash on the end that's this file why doesn't that add appropriate path separators isn't that how that's supposed to work let's print it and see I had helped a package sample package that one help already exists really it does because I thought it was really angry about that let's remove that let's quit and restart can they ever hurts to quit and restart so now my browse available help I don't see it in there and if I said add help to package and picked sample package error adding unable to create the document root index file or help file so the root path was that the index path was actually correct but it says unable to load it's me saying unable to load so the issue isn't that it can't do it because if we look here it very clearly created the appropriate files that is the problem right there let's go back to here and just to verify if we did POSIX path this what do we end up with the appropriate thing so if I said res equals POSIX path join and what we wanted to join was the packages folder and the package name and the document root and the hyper help Piper help Jason and did that and then also came to the top of the file and said import POSIX path thusly and quit and opened the terminal and went to the packages directory and looked at sample package and remove the help and exited and then restarted sublime when you're starting to see why sometimes when I work on this sort of thing I create a stub type action now if I say I'm sorry a sandbox type action to stub out the amount of stuff that has to load and help to package and I picked sample package I'm gonna take that off error adding help unable to create the document root index or help file and the index path is packages sample package help hyper help global name join is not ah why must I do that every time it's not it's not that man it go wow that's extra wrong oh just keep doing it OS top path dot joined like that okay now I'm gonna do that again and quit and restart and add helped a package sample package I keep opening the console but that's not going to help because it needs to close so that the input panel can open why is it mad now that one quit terminal you know I should just leave this open right how many times do I have to do it before it reoccurs to me that I should just leave it open so I could keep coming back and doing that not gonna lie that's been irritating me a little bit as of late – if you try to interact with the command palette before things fully load the subversion package gets really unhappy about it and it's been a long time since I've used subversion I should probably just disable that and help to package sample package help without initial help files created for and let's check that out that actually looks as one might expect it to look huzzah so we can say open created files and yeah that's good get rid of that one and over here in the help we need to go back one okay so if we're gonna do that then we want to fix the other part of this – which is this and we want to say POSIX path dot go away pop-up join the doc root and I for help Jason and whoops that's the wrong one that one boy I'm really persisting and typing of that aren't I the other one is index dot txt and then I could remove those and that seems to work and we make sure that help is gone and we quit and we restart and if I said add help to package and sample package and this time I left these slash on it still looks correct so great that's perfect now with that in place let's go back through and make some notes on this and how we think things should be fixed here other than this one let's see there's your template so that part was cool I mean except for actually we could say this this should use a template from a file instead I imagine it would still have to be formatted that way but at least it would look a little nicer and we also want to do that here maybe there could even be more than one and you could make your own templates that's a nice feature help adder let's add one here that says maybe this could be partially done in the core or something at the very least can we get the core to be the only place where the red X for this is stored so that this package will always work ok and this should that maybe have a customisable snippet that seems like something maybe there could even be a way where you could have package based snippets somehow maybe with extra metadata stored in the index file for use by the authoring tool that would know what resources to use for this sort of thing maybe pulling specifying the package resource to use otherwise it falls back to a default then if you're creating topics in a help system where you wanted them to follow a specific format that would totally work this should perhaps have a customizable snippet to fill out the help file I'm not sure we could specify that it had to have certain fields that one's probably cool except that it needs to support files that are packed because it doesn't currently hyper helped author create index that's the one we're working on we don't need that anymore we don't need that anymore have any more of those that part looks a little nicer and here we go norm path now to gnorm path always remove oh yeah gnorm path seems to remove stuff now I do still have that other window opened that one we looked at the hair to do to normalize by collapsing redundant separators and up references redundant separators and up level references how does it know that this slash on the end of a path is actually redundant in that case I mean that works right but if I did that how does it know that that's not a directory what if I did because this might also be interesting and if we tested it here on our little windows yeah continue oh I can't click that here can i that's cool I was curious if that was a horrible security hole I'll use the mouse behind me to do that posix path Oh actually if I did this first of all it said X is equal to this that's the path POSIX path dot norm path X it doesn't do anything with it did we not determine that the whole point of POSIX path norm path is to swap the path separators maybe not about so though on Windows that converts forward slashes to backward slashes well you say that maybe POSIX path doesn't because it assumes that the paths are already in that format I could see that this is we're not being a Python guru really gets in your way you know that doesn't make anything either so that's something consider for their as opposed say this maybe this should ensure that document root is always in the appropriate path format POSIX and if you want to edit an index it just calls open index from the common code which is pretty simplistic reloading help now I think we're getting into actually the meat of something that I know is definitely wrong and I know I have sort of fixed in at least one place but not in all of the places and that is given a file name how do we figure out what package it's in and I don't know exactly where it is in here and I think we're gonna call this stream at nine three we're gonna go about a half hour short because I do have some stuff that I need to ensure that I'm done tonight and I spent a lot of late nights this week getting everything ready and you know climbing behind monitors and being upset that the height of it is slightly different now than it used to be that's unfortunate somewhere in here in one of these things make the file name be relative to the packages folder now I know this command works which is why I need to investigate this more fully and maybe the stream isn't the place to do this but this is that thing I mentioned while not this specifically I don't think we're given a full path spec to a file we need to be able to reverse lookup to see what package it came from and previously it would know that if the resource was packages user help hyper help Jason or you know packages user help sample dot text that because it's in packages user it must be the user package but that is no longer actually an accurate assumption because it's possible for one package to have more than one thing so what it actually needs to do is take the path of the file which needs to be complete from package all the way up to the end of the document root and compare it against the document root of all the loaded help indexes sorted from longest to shortest in case somebody tries to do something crazy like embedding one in the other and if it finds that path anywhere in there then it knows that's the package there's at least one place in hyper help author that's being changed to do that which was part of me making the change to allow multiple packages to begin with but I don't think they've all been done and as a result some things fail and weird in mysterious ways so there's your linty stuff no i the lint seems to work okay but again we really got to comb over this for anything with paths we have made some changes here and we have made ourselves more familiar with this so that's not a bad night's work considering that I haven't gotten a lot of sleep this week and I never really planned anything knowing how this all works is good now one thing I would also like to do here is split this package up sort of like the way override audit is split up with the commands folder that has one command per and things like that because it really does make looking at stuff like this a lot easier I like the idea of having if you just have a couple of commands put them in one file that makes it easier but when there's this many I found it a lot easier after I'd convinced finished the BSR on override audit to edit commands and so with that I think it is probably time to end this particular stream now this wasn't particularly exciting but if you're watching this live remember you have the inside track that sometime tomorrow there's going to be an announcement on the sublime text forum where I'm going to tell people that snappy exists and there's going to be a video but not on this channel because this channel is for my live streams you guys know that because you watch these live streams so subscribe to this channel if you want to know when I'm doing live streams which is unless something terrible happens every Friday at 8 p.m. PST and if I get enough response from people wanting a different day or a different time I'll see if I can accommodate that at least temporarily but my day job and family life sort of preclude me from doing anything like this earlier than 8 o'clock at night Pacific time because I live on the west coast of Canada kind of causes a problem for people that are in other parts of the country but perhaps one or two I could like wake up early or go to bed late or something we could work that out but that video that I talked about is going to not to be jumping on this channel it's gonna be dropping on my other channel my Oh dat nerd channel now I've said this before but of course fingers crossed I have three videos in the can right now one to cover snappy when to cover hyper help and one to cover hyper help author I sort of package of previews and I'm planning on dropping one of them a week which gives me three weeks to come up with more videos to have them in the can and I actually have some recorded stuff for custom build systems and custom exact commands and stuff that I recorded that I was I recorded it and then the dev build for sublime broke it and I wasn't sure what to do with it and then I recorded parts of it to show how it could be fixed by using a relative import in a different non root package folder it's a whole complicated thing which worked it's more complicated to do and that sublime devs reverted the change that broke the original one so I probably could do something with that but I think at this point I want to clean that up a little bit anyway the thing is videos are coming so subscribe to that other channel if you're not already subscribed things are afoot and that I think is going to do it for tonight's slightly shorter than usual live stream but as that exciting things are coming so with all of that said and my coffee all but gone this is Odette nerd performing a salute that you can't see because I don't have a camera asking you as politely as possible to please have a sublime day

Related Posts

Leave a Reply

Your email address will not be published. Required fields are marked *