[asterisk-dev] Final Preview: docs.asterisk.org

[asterisk at phreaknet.org]

On 7/28/2023 8:48 PM, George Joseph wrote:
> On Fri, Jul 28, 2023 at 1:52 PM <asterisk at phreaknet.org 
> <mailto:asterisk at phreaknet.org>> wrote:
>
>
>     It's at the very bottom of the README:
>     > If you're always going to build just 1 branch's dynamic
>     documentation,
>     > you can skip the Makefile..inc file and just place everything in
>     the
>     > main Makefile.inc:
>
>     The first Makefile..inc has an extra period.... world's least
>     important
>     typo.
>
>
> Ahha!   It's 'Makefile.<branch>.inc' in the source README.md but the 
> '<branch>' is getting stripped. :)

Ah, probably should've noticed that, actually, Makefile.inc twice in a 
row doesn't make any sense, if I was actually thinking about it...

>     Circling back to one other thing now that this seems good to go, what
>     exactly did you change for reducing the file sizes / is that
>     included in
>     the current iteration, without mike?
>
>
> The addition of "navigation.prune" under features in mkdocs.yml did 
> most of it, and yes, it's currently included.
>
>     I'm still seeing a lot of
>     extraneous whitespace in the pages. 244 KB per page isn't huge,
>     but just
>     at a cursory glance, 
>
>
> Can you give me an example of an html page that's that big?  Most I 
> see are in the 80-100k range

I think all of them - for example: 
https://docs.asterisk.org/Asterisk_20_Documentation/API_Documentation/Dialplan_Applications/ADSIProg/

This one is "only" 131 KB, but if you go and view source, you can scroll 
down a bit and see often hundreds of newlines, tabs, and spaces at a 
time in a row. I can't work how that's creeping in from the markdown, so 
I don't think it's from the markdown. That's why I thought we might need 
to do it manually, e.g. using tr or something like that. So regardless 
of page size, I think we could likely prune all the pages down just by 
eliminating whitespace.

>
>     I think we could probably cut the size 10-20% just
>     by getting rid of the whitespace. In some places, there are just
>     hundreds of newlines in a row for no reason.
>
>
> Give me an example page.
>
>     If this is just what the
>     tool generates, I understand that, we don't have any control over
>     that,
>     just wanted to know. We could remove it all pretty easily with sed
>     probably, and think could be a final "post processing" step in the
>     Makefile, run recursively on all files. What do you think?
>
>
> I tried to do exactly that but it didn't result in much savings and I 
> got nervous about accidentally deleting multiple "blank" lines without 
> knowing whether you might be in a "<pre>" block or not.   I was going 
> to try html-minifier but just haven't got to it yet.

Yeah, I guess that could be tricky. But how much is the <pre> tag 
actually used? On the page linked above, for example, I only see it 
once, and, ironically, there isn't any extraneous whitespace in it.  I 
took a look at a few different types of pages and this appears to be the 
case for all of them. So in our particular case, it seems like it might 
be okay to do a simple delete, since <pre> shouldn't be affected by 
consecutive whitespace.