Guide rework

[jacmoe]

Some changes needs to be done in the guide. :)

Page toc

• The div class toc should be hidden on large screens (class lg-hidden IIRC) and it should be possible to grab the headers to be used in the scrollspy toc.

Not sure how that is supposed to work but maybe export a small json file for each page with the headers?
Or simply just a regular php that renders the scrollspy toc?
Because of large screens there will be a scrollspy to our right for easy page level navigation.
Like here: http://testing.jacmoe.dk/guide.html

Source code highlight

• Since I am planning to use Highlight.js to render the code snippets, I need the snippets to be clean and not processed (styled up beforehand). (should be done in the apidoc extension: Use highlightphp for code highlighting yiisoft/yii2-apidoc#31)

Should only be

<pre><code> snippet </code></pre>

Optionally, it could be with a class:

<pre><code class="php"> snippet </code></pre>

But Hightlight.js is intelligent enough to choose the right language.

Other changes

• The blockquote info, blockquote warn, etc. should probably be styled to use the class 'yii-warn', 'yii-info', etc.
  It looks better.

<div class="yii-callout yii-callout-success">
  The Basic Project Template is suitable for developing 90 percent of Web applications. It differs
</div>

Instead of just using a blockquote and the word Info:

We have to agree on what markup to use, but it will be much better looking.

[samdark]

How about using https://github.com/scrivo/highlight.php instead of JS version?

[jacmoe]

Because Hightlight.js is widely used? It is almost an industry standard.
I think it is inefficient to do this in php.
Let the client do the work :)

[jacmoe]

I would also like the class para be removed :)

<a href="#event-handlers" class="hashlink">&para;</a><

I find it to be disturbing, and it works anyway.

[jacmoe]

How about using https://github.com/scrivo/highlight.php instead of JS version?

I think it would be wise to use the best of breed tools available.
PHP is awesome, but IMO not for all the things.

[jacmoe]

Just wanted to add another reason to do highlighting on the client:

There is no render specific code in the source so it is easy to update/upgrade/change the renderer - a new theme, maybe, another engine..

[samdark]

@jacmoe we're going to have news. Probably user submitted news and articles as well. These are to provide RSS where it's good to have highlighted code. Which can't be done in JavaScript. Thus highlight.php. It's a direct port of highlight JS using its definition files.

[jacmoe]

How about using the php script then for the RSS feed?

And then hightlight.js for the rest?

Best of both worlds, I think.

Hightlight.js has over 6 thousand stars and over 1 thousand forks.

2015-11-27 21:43 GMT+01:00 Alexander Makarov notifications@github.com:

@jacmoe https://github.com/jacmoe we're going to have news. Probably
user submitted news and articles as well. These are to provide RSS where
it's good to have highlighted code. Which can't be done in JavaScript. Thus
highlight.php. It's a direct port of highlight JS using its definition
files.

—
Reply to this email directly or view it on GitHub
#77 (comment)
.

[samdark]

I know, I've participated in the project long time ago. Still it worth trying PHP one.

[jacmoe]

I said: why not use both? :)
PHP version for the feed and js version for the rest?

EDIT:
should probably use the PHP version for the PDF generator script as well?

[samdark]

Could be used but I see no big reason not to use PHP everywhere...

[jacmoe]

From what I see it requires that the pre code tags be changed throughout the project, or am I being mistaken?

I like the railscasts theme, by the way. :)

[jacmoe]

About the TOC and the guide ..

How about wrapping the indivudual pages in divs and mark them up with Bootstrap grid classes so that we don't need special handling for the headers?

I will make a test with the intro-yii page and link to it from Pastebin when I am done.

[jacmoe]

It turned out to be easy enough:
http://pastebin.com/Lb5TJ5B9

Basically, wrap the page in <div class="row">, the main section in a <div class="col-md-12 col-lg-10"> and make the toc div hidden on large screens.
Then make a new column at the bottom of the file, with the following:

<div class="col-lg-2 visible-lg">
    <nav id="scrollnav" data-spy="affix">
        <ul class="nav hidden-xs hidden-sm">
            <li><a href="#what-is-yii">What is Yii?</a></li>
            <li><a href="#what-is-yii-best-for">What is Yii Best for?</a></li>
            <li><a href="#how-does-yii-compare-with-other-frameworks">How does Yii Compare with Other Frameworks?</a></li>
            <li><a href="#yii-versions">Yii Versions</a></li>
            <li><a href="#requirements-and-prerequisites">Requirements and Prerequisites</a></li>
        </ul>
    </nav>
</div>

Inside the row div, of course.

And the last scrollnav needs the first header that is not included in the toc div.

[jacmoe]

And then the guide page looks like this:

Notice that the layout is fluid for the guide because it is good to have more reading room..

[cebe]

Guide files are pre-rendered and simply delivered on request so using php highlight is the most efficient and most compatible option.

[jacmoe]

So, I am now going to reference the style css in the head of the main layout manually copy the style css and add it to the main css, and add scrivo highlighter to the composer dependencies - because I am going to use that for other pages not in the guide.

As long as it gets to look the best it can be, I am fine with it. :)

Then there is still page TOC and the use of blockquotes in the guide..

The page TOC needs to be dealt with, but it is probably trivial - see my posts above.

[jacmoe]

So, I am doing this:

<?php
use yii\helpers\Html;
$hl = new Highlight\Highlighter();
?>
<!-- start of quickstart -->
<section class="content-separator section-quickstart">
   <div class="container">
    <div class="row">
        <div class="col-md-12">
            <?php $r = $hl->highlight("bash", Html::encode('composer create-project --prefer-dist yiisoft/yii2-app-basic basic')); ?>
            <pre class="hljs <?=$r->language?>"><?=$r->value?></pre>
        </div>
    </div>
   </div>
</section>
<!-- end of quickstart -->

And I am getting this:

[jacmoe]

I am writing on the Getting started page right now and will be putting the library to the test.

[hscstudio]

@jacmoe:

I have idea how if we create gif for installation step.. simple gif

I use this tool https://screentogif.codeplex.com/downloads/get/1480830

[cebe]

if the animation is too long, gif lacks the possibilty of jumping forward/backward and pause it. I do not think a gif is a good idea in this case.

[cebe]

@jacmoe current implementation of the guide navigation on the right adds a hash to the current url when I click to open a topic. This makes the page jump around. Imo that should be removed.

[jacmoe]

I agree but it is the generated data, so it should be changed there, guide and API.

[jacmoe]

It is the hash tags in the headers that needs to be removed. I guess @samdark thought that it was a good idea at the time? Also, as I wrote elsewhere -I am on my phone right now- the page needs some additional work to accomodate the scrollspy at the right of the page..

[cebe]

fixed: 972cd34

[cebe]

@jacmoe about #77 (comment).
I did not really get what you are proposing about which changes need to be made to the HTML structure, but if you change the HTML I can put the correct links in it. Just paste the default links from intro page. I'll replace them with correct ones.

[jacmoe]

1. wrap the page in row/col and add a column at the end of the page, with headers that duplicates the headers at the start of the page, including the page header:

<div class="row">
<div class="col-md-12 col-lg-10">
page content
</div>
<div class="col-lg-2 visible-lg">
    <nav id="scrollnav" data-spy="affix">
        <ul class="nav hidden-xs hidden-sm">
            <li><a href="#what-is-yii">What is Yii?</a></li>
            <li><a href="#what-is-yii-best-for">What is Yii Best for?</a></li>
            <li><a href="#how-does-yii-compare-with-other-frameworks">How does Yii Compare with Other Frameworks?</a></li>
            <li><a href="#yii-versions">Yii Versions</a></li>
            <li><a href="#requirements-and-prerequisites">Requirements and Prerequisites</a></li>
        </ul>
    </nav>
</div>
</div>

Then, a small addition to the div.toc at the top of the page needs to be done, adding the class 'hidden-lg':

<div class="toc hidden-lg"><ol><li><a href="#what-is-yii-best-for">What is Yii Best for?</a></li>
<li><a href="#how-does-yii-compare-with-other-frameworks">How does Yii Compare with Other Frameworks?</a></li>
<li><a href="#yii-versions">Yii Versions</a></li>
<li><a href="#requirements-and-prerequisites">Requirements and Prerequisites</a></li></ol></div>

The pastebin link contains the modified yii start page, but the changes that I outlined here is all that is needed to get this nice scrollspy :)

[jacmoe]

Notice that the first header - What is Yii - is not included in the div.toc, but should be included in the (new) scrollnav at the bottom.
It is only visible on large screens.

[jacmoe]

Beautiful work @cebe 👍
It is really, really nice - I'll see if I can fix the footer issue, but it is almost without flaw :D

[cebe]

we now have highlight.php in apidoc

[hscstudio]

please create development server so we can watch day to day changes @jacmoe

[cebe]

I will set up a box on digitalocean

[cebe]

http://yiiframework.domain-na.me/ I have not set up a database yet so some places may crash with error 500. But most of the things should work already. fixed.

[jacmoe]

Great! 👍

[jacmoe]

It really looks awesome using the new highlighter :)

[cebe]

The blockquote info, blockquote warn, etc. should probably be styled to use the class 'yii-warn', 'yii-info', etc.

seems people have translated these indicators :-/

$ grep -roihP '^> [*\p{L}]+: ' . |sort |uniq 
> ヒント: 
> Atenção: 
> Atención: 
> Aviso: 
> Consejo: 
> Dica: 
> full: 
> Info: 
> Informação: 
> Información: 
> Informações: 
> Informazione: 
> long: 
> medium: 
> Nota: 
> Note: 
> **Note**: 
> Observação: 
> Remarque: 
> short: 
> Suggerimento: 
> Tip: 
> **Tip**: 
> todo: 
> Uwaga: 
> Warning: 
> Внимание: 
> Замечание: 
> Информация: 
> Інформація: 
> Підказка: 
> **Подсказка**: 
> Подсказка: 
> Попередження: 
> **Примечание**: 
> Примечание: 
> **Примітка**: 
> Примітка: 
> Совет: 
> Трюк: 
> 情報: 
> 技巧: 
> 提示: 
> 日本語出力: 
> 注: 
> **注意**: 
> 注意: 
> 补充: 
> 補足: 
> 警告: 

[cebe]

@jacmoe apidoc now renders CSS classes on the block quotes which can be used to style them.
This is the same markup as used by yii 1.1 guide. Styling works like this: https://github.com/yiisoft/yii2-apidoc/blob/12cccbb6c1c9ee2840fddb9d93c14982a9bb0c3f/templates/bootstrap/assets/css/style.css#L79-L101

[jacmoe]

There is one thing that bothers me about the blockquotes and that is the words:

• Info
• Tip
• Warn
• Note

They are redundant once the blockquotes have been styled.
I have written a quick js script that removes that text for the guide page.

Also, the icons that @eshill proposed in #94 could be replaced by FontAwesome because they look better (and because that icon font has a much better license. The glyph icons will be removed from Bootstrap 4).

And, finally:
'Note' and 'Info' means basically the exact same thing in this context, I suggest that we apply same style/icon for them both.

[cebe]

They are redundant once the blockquotes have been styled.

Not really, they make it explicit, what the icon actually means. I think we should keep them. Otherwise we would need a meta document explaining the icons imo. They also make it more accessible in case icons are invisible on screenreader or similar thing.

I have written a quick js script that removes that text for the guide page.

If we agree on removing them this can easily be done in the renderer.

'Note' and 'Info' means basically the exact same thing in this context, I suggest that we apply same style/icon for them both.

No, they are different, see https://github.com/yiisoft/yii2/blob/master/docs/documentation_style_guide.md#blocks

[jacmoe]

I my not very humble opinion it looks stupid.

Silly version:

Better version:

If there are concerns about people not understanding what the icons means, we can put a title on them so that people will become enlightened when they hover over them.

[cebe]

I think we should compare the completely styled versions. removing the "Info:" from the text is easy once we have it.

[jacmoe]

The Bootstrap docs is not even using icons to differentiate between warning and note:

The colour alone makes it obvious what the level of urgency is. It is even cleaner - something that we could consider.

[cebe]

could you come up with other arguments that do not include "stupid", "Silly" and are more objective please? Also "someone else is doing this" does not justify something on its own.

Bootstrap is very minimal. With color and icon the messages stands out more so they are more visible.
The text allows directly reading the importance, e.g. reading the word "Warning" makes it clear for everyone what it is. Keep in mind that we are translating this also into different languages around the world. Somewhere else a red color may not say the same about importance that it may say for you.

I think @eshill's layout is already really nice, unless there are big issues with it, we should just go with it and not waste time in dicussing details. We can always change things later, its important to get it done now.

[jacmoe]

Get lost

[mdomba]

all needed changes has been done, issue closed