www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Improving the D documentation web presentation

reply WebFreak001 <d.forum webfreak.org> writes:
as some of you might know, there are 2 versions of the official 
phobos documentation:

ddoc based (https://dlang.org/phobos/index.html)
ddox based (https://dlang.org/library/index.html)

I actually quite like the ddox based documentation for future 
extending because it can contain a lot more information per 
symbol and also allows us to write much larger examples for 
standard library functionality. I think this one has better SEO 
too.

However I still see myself all the time on the ddoc based site as 
it is simply more polished and faster to find multiple symbols in 
a module.

So here I have a few small proposals how we could improve on the 
presentation of the ddox page. I will be referencing to the .NET 

pretty good job.

Polish the overview: the descriptions of modules are currently 
all kinds of messed up stuff (tables, headings, deprecated 
warnings), having nicer descriptions (only short strings, no 
duplicates, no empty ones) would be a good start for this 
overview page. Also because the left sidebar just shows the same 
as the list of modules, it would probably be smart to remove the 
left sidebar so we have more space for description text. 
Additionally instead of having all APIs in there, I would propose 
to let the user first select the kind of project they are 
interested in (phobos, druntime, dmd) and then only show the 
modules for that project. See 
https://docs.microsoft.com/en-us/dotnet/api/ for an example.

Move the search: the search at the top right is a google search 
on all other D pages. On the ddox it's a quick and easy to use 
search with a different functionality. I think for showing this 
to the user, it should be moved to the left above the module 
tree. This search should also be visible on the index if the 
sidebar is removed there.

Improve navigation: my biggest usability complaint with the ddox 
API pages is that you have to navigate so much to look through 
different symbols inside a module, compared to the ddoc page. 
Much like in the .NET docs, we should show a tree of symbols in 
the sidebar. I think this could nicely fit and also be easier to 
read if we slightly increase the padding per entry, make the 
sidebar scrollable (maybe also add position: sticky) and scroll 
to the currently selected module by default. I think we can also 
improve how the currently active selection looks, because right 
now it is just a darker shade of red with an underline. To not 
overload this with symbols, only symbols in the currently active 
module should be shown as children of a module.

What is your thought on the current ddox and ddoc documentation? 
Which one do you like and/or use more?
May 25
next sibling parent reply Paul Backus <snarwin gmail.com> writes:
On Monday, 25 May 2020 at 13:56:10 UTC, WebFreak001 wrote:
 as some of you might know, there are 2 versions of the official 
 phobos documentation:
[...]
 Move the search: the search at the top right is a google search 
 on all other D pages. On the ddox it's a quick and easy to use 
 search with a different functionality.
[...]
 Improve navigation: my biggest usability complaint with the 
 ddox API pages is that you have to navigate so much to look 
 through different symbols inside a module, compared to the ddoc 
 page.
[...]
 What is your thought on the current ddox and ddoc 
 documentation? Which one do you like and/or use more?
IMHO, dpldocs.info is the only version that gets all of this right. Search easily accessible at the top of the page, module contents listed in a sidebar on the left, and detailed pages on each symbol for easy navigation and cross-referencing. Mostly I access it via duckduckgo's !dpldocs bang [1], which lets me type search queries directly into my browser's address bar, or a shell script I've bound to vim's `K` command (which looks up the identifier under the cursor). It's super convenient. [1] https://duckduckgo.com/bang
May 25
parent reply WebFreak001 <d.forum webfreak.org> writes:
On Monday, 25 May 2020 at 14:54:44 UTC, Paul Backus wrote:
 On Monday, 25 May 2020 at 13:56:10 UTC, WebFreak001 wrote:
 as some of you might know, there are 2 versions of the 
 official phobos documentation:
[...]
 Move the search: the search at the top right is a google 
 search on all other D pages. On the ddox it's a quick and easy 
 to use search with a different functionality.
[...]
 Improve navigation: my biggest usability complaint with the 
 ddox API pages is that you have to navigate so much to look 
 through different symbols inside a module, compared to the 
 ddoc page.
[...]
 What is your thought on the current ddox and ddoc 
 documentation? Which one do you like and/or use more?
IMHO, dpldocs.info is the only version that gets all of this right. Search easily accessible at the top of the page, module contents listed in a sidebar on the left, and detailed pages on each symbol for easy navigation and cross-referencing. Mostly I access it via duckduckgo's !dpldocs bang [1], which lets me type search queries directly into my browser's address bar, or a shell script I've bound to vim's `K` command (which looks up the identifier under the cursor). It's super convenient. [1] https://duckduckgo.com/bang
yep dpldocs is pretty good, we should really promote it, maybe as a replacement to the current ddox one as it is quite similar. Small things I think could be improved: - show all overloads extended, or at least a list of method names with types like in https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.process.start?view=netcore-3.1 - automatically collect all referenced functions (in the docs) in the See_Also section - or can you think of a case where this is undesirable? Also do you think the const(char)[] might be confusing to newcomers?
May 27
parent reply aberba <karabutaworld gmail.com> writes:
On Wednesday, 27 May 2020 at 07:34:50 UTC, WebFreak001 wrote:
 On Monday, 25 May 2020 at 14:54:44 UTC, Paul Backus wrote:
 [...]
yep dpldocs is pretty good, we should really promote it, maybe as a replacement to the current ddox one as it is quite similar. Small things I think could be improved: - show all overloads extended, or at least a list of method names with types like in https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.process.start?view=netcore-3.1 - automatically collect all referenced functions (in the docs) in the See_Also section - or can you think of a case where this is undesirable? Also do you think the const(char)[] might be confusing to newcomers?
dpldocs is functionally the best. Not aesthetics though :). If we could give it the ddoc look and feel, that'll be complete.
May 27
next sibling parent Guillaume Piolat <first.last gmail.com> writes:
On Wednesday, 27 May 2020 at 09:51:16 UTC, aberba wrote:
 dpldocs is functionally the best. Not aesthetics though :). If 
 we could give it the ddoc look and feel, that'll be complete.
+1 dpldocs also has a hidden functionality of searching across all packages whose dpldocs is generated
May 27
prev sibling parent reply WebFreak001 <d.forum webfreak.org> writes:
On Wednesday, 27 May 2020 at 09:51:16 UTC, aberba wrote:
 [...]

 dpldocs is functionally the best. Not aesthetics though :). If 
 we could give it the ddoc look and feel, that'll be complete.
I tinkered a little bit with the HTML and CSS of dpldocs, here are some changes I made: Screenshots: Before: https://i.imgur.com/bQ60YWA.png After: https://i.imgur.com/hJOGhrR.png Before: https://i.imgur.com/i2tow79.png After: https://i.imgur.com/JKingMa.png Module: https://i.imgur.com/PmJlkoo.png I didn't touch the headerbar, I think the design should just be copied from the homepage there. HTML changes: - Added a span inside the h1 title with class .name - Prepended the symbol kind as text to the title ("Function") - Add `lang="en"` to <html> JS code to preview this: document.body.parentElement.setAttribute("lang", "en") - In the Parameters section move all the types into the parameter names JS code to preview this: document.querySelectorAll(".parameter-descriptions dt").forEach(dt => dt.appendChild(dt.nextElementSibling.querySelector(".parameter-type"))) - Delete the empty parameter type holders JS code to preview this: document.querySelectorAll(".parameter-type-holder:empty").forEach(a => a.parentElement.removeChild(a)) - In the Parameters section delete the "Type:" string for each argument JS code to preview this: document.querySelectorAll(".parameter-descriptions .parameter-type-holder").forEach(t => t.removeChild(t.childNodes[0])); - for each pre.d_code.highlighted, insert a <header> tag before it, move the "Copy to Clipboard" and "Toggle Line Numbers" buttons into the header tag, wrap everything in a <div class="codeblock"> JS code to preview this: document.querySelectorAll("pre.d_code.highlighted").forEach(c=>{c.parentElement.insertBefore(h=document.createElement("header"),c);while(b=h.previousElementSibling,b.tagName=="BUTTON")h.prepend(b);h.parentElement.insertBefore(w=document.createElement("div"),h);w.className="codeblock";w.appendChild(h);w.appendChild(c)}) - Disable Line numbers by default for short code (<15 lines) - Delete & Disable the dynamic style (resize style) JS code to preview this: window.onresize = undefined; var d = document.querySelector("#dynamic-style"); d.parentElement.removeChild(d); - In the small overloads buttons (.overloads>li .overload-signature), remove all parameter type qualifiers and default values, only keep names and basic types Quick apply JS: // manually add function kind & span.name // manually disable line numbers in short code blocks // manually edit overload buttons to only have argument types & names document.body.parentElement.setAttribute("lang", "en") document.querySelectorAll(".parameter-descriptions dt").forEach(dt => dt.appendChild(dt.nextElementSibling.querySelector(".parameter-type"))) document.querySelectorAll(".parameter-type-holder:empty").forEach(a => a.parentElement.removeChild(a)) document.querySelectorAll(".parameter-descriptions .parameter-type-holder").forEach(t => t.removeChild(t.childNodes[0])); document.querySelectorAll("pre.d_code.highlighted").forEach(c=>{c.parentElement.insertBefore(h=document.createElement("header"),c);while(b=h.previousElementSibling,b.tagName=="BUTTON")h.prepend(b);h.parentElement.insertBefore(w=document.createElement("div"),h);w.className="codeblock";w.appendChild(h);w.appendChild(c)}) window.onresize = undefined; var d = document.querySelector("#dynamic-style"); d.parentElement.removeChild(d); Additional work to be done: Make link for `const(char)[]` as type explaining that it works with strings and char arrays. Also embed the graph from and link to https://dlang.org/spec/const3.html#implicit_qualifier_conversions Make link for `size_t` and `ptrdiff_t` as type explaining that it's an (unsigned) integer type, commonly (u)int or (u)long with link to https://dlang.org/spec/type.html#size_t CSS additions: #page-body #page-content { padding-left: 1.75em; } #page-content h1:first-child { margin-top: 2rem; font-size: 2.2rem; font-family: "Roboto Slab", sans-serif; font-weight: normal; margin-bottom: 0.5rem; } #page-content h1:first-child + .breadcrumbs { margin-top: 0; } #page-content h1 .name { font-family: Consolas, "Bitstream Vera Sans Mono", "Andale Mono", Monaco, "DejaVu Sans Mono", "Lucida Console", monospace; } #page-content h2, #page-content h3 { margin-top: 1.5em; font-family: "Roboto Slab", sans-serif; font-weight: normal; } #page-content h2 { font-size: 1.6rem; } #page-content h3 { font-size: 1.26rem; } #table-of-contents, .enum-members, .documentation-comment .tip, .documentation-comment .note, .documentation-comment .warning, .documentation-comment .pitfall, .documentation-comment li, .documentation-comment p { font-size: 1rem; } #page-body #page-nav { padding-left: 1em; padding-right: 0; border-left-style: solid; border-left-width: 1px; overflow: unset; } #page-nav ul { list-style: none; } #page-nav .type-separator { margin-bottom: 0.25em; } #page-nav a { box-sizing: border-box; font-family: "Roboto Slab", sans-serif; padding: 1pt 0.25em 1pt 0.5em; text-overflow: ellipsis; overflow: hidden; } #page-nav a:hover { position: relative; overflow: visible; z-index: 10; background-color: rgb(245, 245, 245); width: max-content; } #page-nav a.parent { line-height: 0.9; overflow: visible; } #page-nav a.parent:first-child { margin-top: 0.75em; } tt.D, .inline-code, .parameter-descriptions .parameter-name { color: black; font-weight: 500; background-color: #f2f2f2; padding: 0px 0.5ex; border-radius: 2px; } .parameter-descriptions .parameter-name { margin-right: 1.5rem; font-weight: bold; padding: 0.25ex 0.75ex; } .parameter-descriptions dd { margin-left: 1.5em; } .parameter-descriptions dd p:first-child { margin-top: 0.5em; } .parameter-descriptions dt:not(:first-child) { margin-top: 1.5em; } .codeblock { border: solid 1px #ccc; padding: 0; margin: 0; } .codeblock header { background-color: #e8e8e8; padding: 0; display: flex; justify-content: flex-end; } .codeblock header:before { display: inline-block; content: "Example"; justify-content: flex-start; flex-grow: 1; padding: 0.25em 1em; font-weight: bold; } .codeblock header button { /* TODO: add :before class with icons here (copy, line numbers) */ appearance: none; -webkit-appearance: none; -moz-appearance: none; margin: 0; padding: 0 1em; background-color: transparent; border: none; border-left: 1px solid #ccc; cursor: pointer; } .codeblock header button:hover { background-color: rgba(255, 255, 255, 0.5); } .codeblock pre.d_code { border: none; border-top: solid 1px #ccc; margin: 0; padding: 1em 0; max-width: unset !important;; } .hide-line-numbers .codeblock .with-line-wrappers, .codeblock pre.d_code:not(.with-line-wrappers) { padding: 1em; } .codeblock .with-line-wrappers .br { margin-right: 1em; } .annotated-prototype .overloads li { margin: 0; } .member-list .dt, .overload-option, pre { max-width: unset; } .documentation-comment p { hyphens: auto; } .declaration-prototype, .aggregate-prototype, .function-prototype { margin-left: 0; margin-right: 0; }
May 27
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 27 May 2020 at 12:55:07 UTC, WebFreak001 wrote:
 [...]
So I'm gonna integrate at least some of this tonight or tomorrow... but probably not all of it.
 - Prepended the symbol kind as text to the title ("Function")
like idk the value of this.
 - Disable Line numbers by default for short code (<15 lines)
fun fact i think right now my limit is 7 lines...
 - Delete & Disable the dynamic style (resize style)
I know I put that in for a reason but forgot what it was... what was it breaking for you?
   max-width: unset !important;;
these max widths too btw were there to keep the main content from going wide just because of some long line in an example. I gotta extract the diffs and put it in here to try on the sdpy docs.
 .documentation-comment p {
   hyphens: auto;
 }
i hate hyphens tho
May 28
parent WebFreak001 <d.forum webfreak.org> writes:
On Thursday, 28 May 2020 at 17:41:25 UTC, Adam D. Ruppe wrote:
 On Wednesday, 27 May 2020 at 12:55:07 UTC, WebFreak001 wrote:
 [...]
So I'm gonna integrate at least some of this tonight or tomorrow... but probably not all of it.
 - Prepended the symbol kind as text to the title ("Function")
like idk the value of this.
idk either but the ddox page renders it. Just like "Class", "Struct", "Alias", "Interface", "Template", "Mixin Template", "Function", "Variable", "Enum"
 - Disable Line numbers by default for short code (<15 lines)
fun fact i think right now my limit is 7 lines...
 - Delete & Disable the dynamic style (resize style)
I know I put that in for a reason but forgot what it was... what was it breaking for you?
it made the overload tabs smaller than max width. Also resizing with JS is pretty inefficient, better move it to CSS.
   max-width: unset !important;;
these max widths too btw were there to keep the main content from going wide just because of some long line in an example.
I wrapped the whole code block in a new div, which made the max-width inside the code blocks no longer necessary I think. At least the parent div should now get that max width if it was important.
 I gotta extract the diffs and put it in here to try on the sdpy 
 docs.

 .documentation-comment p {
   hyphens: auto;
 }
i hate hyphens tho
I don't :p
May 28
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 27 May 2020 at 12:55:07 UTC, WebFreak001 wrote:
 - In the small overloads buttons (.overloads>li 
 .overload-signature), remove all parameter type qualifiers and 
 default values, only keep names and basic types
I'm not sure I can do this without more invasive changes to the generator. But I did most the changes here you can refresh to reload: http://dpldocs.info/experimental-docs/arsd.simpledisplay.SimpleWindow.this.1.html only regenerated sdpy dox with the new html btw. I'm pretty sure I missed a few spots applying your new stuff, and I rejected a few pieces. But.... I don't hate it so far.
 Make link for `const(char)[]` as type explaining that it works 
 with strings and char arrays. Also embed the graph from and 
 link to 
 https://dlang.org/spec/const3.html#implicit_qualifier_conversions

 Make link for `size_t` and `ptrdiff_t` as type explaining that 
 it's an (unsigned) integer type, commonly (u)int or (u)long 
 with link to https://dlang.org/spec/type.html#size_t
Once upon a time, I was going to do a bunch of links like this. Never actually got around to.... almost any of them. But i like the idea. I still need to check it across more pages and other browsers before going all the way. But I think this is gonna be ok. I still don't love the "Example" header - not all those are examples (notably view source!). So might tweak that. BTW on the hard questions: http://dpldocs.info/experimental-docs/arsd.cgi.Cgi.this.2.html the delegates in there always look bleh. idk.
May 28
parent reply WebFreak001 <d.forum webfreak.org> writes:
On Friday, 29 May 2020 at 02:12:34 UTC, Adam D. Ruppe wrote:
 On Wednesday, 27 May 2020 at 12:55:07 UTC, WebFreak001 wrote:
 - In the small overloads buttons (.overloads>li 
 .overload-signature), remove all parameter type qualifiers and 
 default values, only keep names and basic types
I'm not sure I can do this without more invasive changes to the generator.
Yeah but for some functions I think it could make it much more readable if you did do that. You could use libdparse and try to parse that declaration as variable definition + trailing semicolon to exactly find the parts of the expression.
 But I did most the changes here you can refresh to reload:

 http://dpldocs.info/experimental-docs/arsd.simpledisplay.SimpleWindow.this.1.html

 only regenerated sdpy dox with the new html btw.

 I'm pretty sure I missed a few spots applying your new stuff, 
 and I rejected a few pieces. But.... I don't hate it so far.
meh, still 1.1rem font size :p can you maybe comment on the overload changes a little? Especially keeping the margins around the whole block and keeping the ridge border + 2px borders between buttons.
 Make link for `const(char)[]` as type explaining that it works 
 with strings and char arrays. Also embed the graph from and 
 link to 
 https://dlang.org/spec/const3.html#implicit_qualifier_conversions

 Make link for `size_t` and `ptrdiff_t` as type explaining that 
 it's an (unsigned) integer type, commonly (u)int or (u)long 
 with link to https://dlang.org/spec/type.html#size_t
Once upon a time, I was going to do a bunch of links like this. Never actually got around to.... almost any of them. But i like the idea.
Maybe it's worth writing that down somewhere in some issue tracker or todo comment
 I still need to check it across more pages and other browsers 
 before going all the way. But I think this is gonna be ok.

 I still don't love the "Example" header - not all those are 
 examples (notably view source!). So might tweak that.
I was just thinking of some content to fill there, might be worth because .NET can be used from multiple languages.
 BTW on the hard questions:

 http://dpldocs.info/experimental-docs/arsd.cgi.Cgi.this.2.html

 the delegates in there always look bleh. idk.
hm seems ok imo Also about the prefix with "Function" part again: In the sidebar you already have the headers for these things, why not use those? Found another small area for improvement on enum members: .enum-members { min-width: 60%; margin: auto; } /* just added .enum-members .enum-member-name to the inline code definition */ tt.D, .inline-code, .parameter-descriptions .parameter-name, .enum-members .enum-member-name { color: black; font-weight: 500; background-color: #f2f2f2; padding: 0px 0.5ex; border-radius: 2px; } .enum-member .enum-attributes:empty { display: none; } .enum-members td, .enum-members th { padding: 0.25em 0.5em; } .enum-members th { background-color: #e8e8e8; color: black; } .enum-members tr.enum-member > td:nth-child(2) > div:only-child:empty:before { display: inline; content: "n/a"; color: rgba(0, 0, 0, 0.4); font-style: italic; } Before: https://i.imgur.com/zjHPMWI.png After: https://i.imgur.com/twNnJxd.png
May 29
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 29 May 2020 at 07:39:59 UTC, WebFreak001 wrote:
 meh, still 1.1rem font size :p
lol i commented it out.... then copy/pasted it back in right after without realizing it. So I thought I removed it then was like "huh that actually still looks pretty good" and was gonna live with it. But idk I really prefer the body text standing out a little but i might just hack that for me. Regardless it was just a mistake so changed it now. Just... I seriously hate it. And changing my browser's default font size breaks other sites (I know it isn't supposed to but like i have to use garbage sometimes). Like now forum.dlang.org is killer cuz it does `font-size: 120%` like so many other sites. ugh ugh ugh. whatever i'll hack it somehow on my end.
 can you maybe comment on the overload changes a little? 
 Especially keeping the margins around the whole block and 
 keeping the ridge border + 2px borders between buttons.
i copy/pasted it in the file but it was overridden somewhere else. my css is such a ball of spaghetti so getting your css patch actually applied was kinda a mess (actually if you can send me a patch file instead of blocks like this it would be easier - I don't preprocess the css at all so just downloading it from the site and running diff over it would be good enough). try it now anyway
 I was just thinking of some content to fill there, might be 


Yes, I put the language in a little tag on teh upper right. here for example: http://dpldocs.info/experimental-docs/arsd.simpledisplay.html#windows-tips So maybe I can move that tag into there... I'll play with it.
 Also about the prefix with "Function" part again: In the 
 sidebar you already have the headers for these things, why not 
 use those?
I'm not even sure I like that separation in the sidebar. I kinda feel it is less usable than a simple alphabetic listing. I've considered removing it many times. Similarly, I kinda hate the grey background on inline code (tt.D, .inline-code, etc). I stole that from Stack Overflow I think to replace simple bolding, like the ddoc Phobos style does (and I kept that on enum members and function params)... but I kinda prefer the bolding. Just it was a bit loud inline. But for headers like enum values and param names, I definitely prefer it to the background.
   content: "n/a";
also not in love with this.... but i don't hate it either so idk. maybe just "undocumented" would be better ima play some more
May 29
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 29 May 2020 at 07:39:59 UTC, WebFreak001 wrote:
 Yeah but for some functions I think it could make it much more 
 readable if you did do that. You could use libdparse and try to 
 parse that declaration as variable definition + trailing 
 semicolon to exactly find the parts of the expression.
LOL I just went to look at the source to confirm what I was already doing and check this out: void putSimplfiedArgs(T)(MyOutputRange output, const T decl) { // FIXME: do NOT show default values here if(decl.parameters) output.putTag(toHtml(decl.parameters).source); } So yeah it is just a matter of making it work. Probably doing foreach param instead of using the array would be good enough since it is already parsed.
May 29
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 29 May 2020 at 07:39:59 UTC, WebFreak001 wrote:
 meh, still 1.1rem font size :p
So after removing this some of the irc gang said they don't like how big the sidebar nav is. It is the same as it was before.... but with the main body shrunk and with the different fonts they look out of proportion. So my options seem to be: 1) tell users to deal with it 8) 2) change the nav font to match the body font. That's actually the way I used to do it but someone previously thought the code font looked better so I changed it... hesitant to change it back since I'm trying to please everyone. 3) Make the nav text a bit smaller, like 0.9rem or whatever. 4) put my precious 1.1rem back. What's your view?
May 29
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 29 May 2020 at 21:12:18 UTC, Adam D. Ruppe wrote:
 What's your view?
whoops your old message mentioned the font and i didn't apply it. so let's see: http://dpldocs.info/experimental-docs/arsd.cgi.Cgi.html i think that's p ok, maybe because it uses the roboto the people who wanted it changed will like this too.
May 29
prev sibling next sibling parent WebFreak001 <d.forum webfreak.org> writes:
On Friday, 29 May 2020 at 21:12:18 UTC, Adam D. Ruppe wrote:
 On Friday, 29 May 2020 at 07:39:59 UTC, WebFreak001 wrote:
 meh, still 1.1rem font size :p
So after removing this some of the irc gang said they don't like how big the sidebar nav is. It is the same as it was before.... but with the main body shrunk and with the different fonts they look out of proportion. So my options seem to be: 1) tell users to deal with it 8) 2) change the nav font to match the body font. That's actually the way I used to do it but someone previously thought the code font looked better so I changed it... hesitant to change it back since I'm trying to please everyone. 3) Make the nav text a bit smaller, like 0.9rem or whatever. 4) put my precious 1.1rem back. What's your view?
hm one suggestion I have: change the width:70ch to width:78ch (3 alphabets) to make it look more fitting :p If it was 70ch on 1.1rem before, that makes 77 units which are 77ch on 1rem. 78ch just to make it align with alphabets because everyone measures text length in alphabets (26 chars) :p Also about the CSS mess: I'm not changing the CSS actually, I use the firefox stylesheet editor which just appends one CSS file to the end. So if you copy paste my CSS definitions to the very end of your CSS file it would work as expected, however actually merging them properly is better maintenance-wise.
May 30
prev sibling parent Gabriel <iamgabrielhum gmail.com> writes:
On Friday, 29 May 2020 at 21:12:18 UTC, Adam D. Ruppe wrote:
 On Friday, 29 May 2020 at 07:39:59 UTC, WebFreak001 wrote:
 meh, still 1.1rem font size :p
So after removing this some of the irc gang said they don't like how big the sidebar nav is. It is the same as it was before.... but with the main body shrunk and with the different fonts they look out of proportion. So my options seem to be: 1) tell users to deal with it 8) 2) change the nav font to match the body font. That's actually the way I used to do it but someone previously thought the code font looked better so I changed it... hesitant to change it back since I'm trying to please everyone. 3) Make the nav text a bit smaller, like 0.9rem or whatever. 4) put my precious 1.1rem back. What's your view?
Fonts and Fonts: While some experts argue that these terms mean two different things, modern usage is synonymous. In web context, a font or font is a set of letters, symbols and punctuation marks of a similar design and packed together into a single computer file. Font family: A font family includes many different fonts that are similar except for stroke thickness and italics. If you plan to use normal, bold and italicized fonts, include at least three fonts or fonts for each font family you intend to use. Typography: A broad term covering font choices as well as topics such as color, size, character spacing, line drawing and alignment. Web typography is the discipline of designing text for web presentation.
Jun 07
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 5/25/20 9:56 AM, WebFreak001 wrote:
 What is your thought on the current ddox and ddoc documentation? Which 
 one do you like and/or use more?
Lots of chatter about that over the years. I grew to appreciate having both options. (We're not alone, e.g. GNU does the same.)
May 25
parent reply Andre Pany <andre s-e-a-p.de> writes:
On Monday, 25 May 2020 at 16:12:14 UTC, Andrei Alexandrescu wrote:
 On 5/25/20 9:56 AM, WebFreak001 wrote:
 What is your thought on the current ddox and ddoc 
 documentation? Which one do you like and/or use more?
Lots of chatter about that over the years. I grew to appreciate having both options. (We're not alone, e.g. GNU does the same.)
Unfortunately while searching for `dlang spawnShell` or similar, the first hit on google is https://dlang.org/library/std/process/spawn_shell.html The function description is not that good: Pid spawnShell ( scope const(char)[] command, File stdin = makeGlobal(), File stdout = makeGlobal(), File stderr = makeGlobal(), scope const(string[string]) env = cast(const(string[string]))null, Config config = cast(Config)0, scope const(char)[] workDir = null, scope string shellPath = nativeShell() ) trusted; comparing to https://dlang.org/phobos/std_process.html#spawnShell trusted Pid spawnShell(scope const(char)[] command, File stdin = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr = std.stdio.stderr, scope const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null, scope string shellPath = nativeShell); As I know this issue, I refuse to use the first hit on google, but for other users, this is quite confusing / disturbing I assume. Kind regards André
May 26
parent WebFreak001 <d.forum webfreak.org> writes:
On Wednesday, 27 May 2020 at 06:38:46 UTC, Andre Pany wrote:
 On Monday, 25 May 2020 at 16:12:14 UTC, Andrei Alexandrescu 
 wrote:
 On 5/25/20 9:56 AM, WebFreak001 wrote:
 What is your thought on the current ddox and ddoc 
 documentation? Which one do you like and/or use more?
Lots of chatter about that over the years. I grew to appreciate having both options. (We're not alone, e.g. GNU does the same.)
Unfortunately while searching for `dlang spawnShell` or similar, the first hit on google is https://dlang.org/library/std/process/spawn_shell.html The function description is not that good: Pid spawnShell ( scope const(char)[] command, File stdin = makeGlobal(), File stdout = makeGlobal(), File stderr = makeGlobal(), scope const(string[string]) env = cast(const(string[string]))null, Config config = cast(Config)0, scope const(char)[] workDir = null, scope string shellPath = nativeShell() ) trusted; comparing to https://dlang.org/phobos/std_process.html#spawnShell trusted Pid spawnShell(scope const(char)[] command, File stdin = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr = std.stdio.stderr, scope const string[string] env = null, Config config = Config.none, scope const(char)[] workDir = null, scope string shellPath = nativeShell); As I know this issue, I refuse to use the first hit on google, but for other users, this is quite confusing / disturbing I assume. Kind regards André
oh yep you are right, the values are quite a mess. I just searched for "dlang run program" as I would imagine some newcomer might do. After "Run D program locally - Dlang Tour" the second link is https://dlang.org/library/std/process/execute.html auto Tuple!(int,"status",string,"output") execute ( scope const(char[])[] args, const(string[string]) env = cast(const(string[string]))null, Config config = cast(Config)0, ulong maxOutput = 18446744073709551615LU, scope const(char)[] workDir = null ) trusted; auto Tuple!(int,"status",string,"output") execute ( scope const(char)[] program, const(string[string]) env = cast(const(string[string]))null, Config config = cast(Config)0, ulong maxOutput = 18446744073709551615LU, scope const(char)[] workDir = null ) trusted; Compared to trusted auto execute(scope const(char[])[] args, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null); trusted auto execute(scope const(char)[] program, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null); trusted auto executeShell(scope const(char)[] command, const string[string] env = null, Config config = Config.none, size_t maxOutput = size_t.max, scope const(char)[] workDir = null, string shellPath = nativeShell); Things I would like to see improved on the documentation page in general: - use structured standard sections (See_Also, Examples) - maybe automatically generate See_Also from mentioned symbols too - maybe a copy of the module documentation? It's exactly what I had searched for (see https://dlang.org/phobos/std_process.html) and I think it would improve discovery in the ddox style documentation. Some module documentation might need to be adjusted and general examples should probably be omitted. - we need much more full examples per function! Compare this to of commonly used types. - to avoid code duplication for this, we need some way to embed examples or other documentation as references inside documentation Also as an example for a better documented signature of that execute function to show to a beginner I would suggest: auto Tuple!(int,"status", string,"output") execute( scope const(char[])[] args, const string[string] env = null, Config config = Config.none, ulong maxOutput = size_t.max, scope const(char)[] workDir = null ) trusted; auto Tuple!(int,"status", string,"output") execute( scope const(char)[] program, const string[string] env = null, Config config = Config.none, ulong maxOutput = size_t.max, scope const(char)[] workDir = null ) trusted; * fixed the default values (made them like in the ddoc docs) * made const for an entire type format like scope (I think it's more obvious what it means in a formatted context like this) * horizontally aligned scope/const/in/out, type, argument name, default value * horizontally aligned across all definitions * special formatting for Tuple because it's a common type
May 27
prev sibling parent reply bauss <jj_1337 live.dk> writes:
On Monday, 25 May 2020 at 13:56:10 UTC, WebFreak001 wrote:
 as some of you might know, there are 2 versions of the official 
 phobos documentation:

 ddoc based (https://dlang.org/phobos/index.html)
 ddox based (https://dlang.org/library/index.html)
ddox because it also adds documentation for the compiler lmao.
May 29
parent James Lu <jamtlu gmail.com> writes:
The Dlang installer for macOS is very nice because it brings an 
offline copy of the documentation. I would suggest making it load 
CSS fonts asynchronously, instead of blocking page navigation and 
page render until a font times out.
May 30