Improve documentation layout

docs/2.0/field-values.md

@@ -164,9 +164,9 @@ Item::true(): self;
 Item::false(): self;
 ```
 
-On error, those named constructor will throw an exception, if you do not want an exception
-and prefer a softer approache where the named constructor would instead return `null`, you
-can prepend the named constructor with the `try` prefix.
+On error, the listed named constructors will throw an exception, if you do not want an exception
+and prefer a softer approach where the named constructor would instead return `null`, you
+can prepend the listed named constructor with the `try` prefix.
 
 ```php
 Item::fromDecimal('42'); // will throw because the value is a string;

docs/2.0/rfc-usage.md

@@ -5,10 +5,13 @@ title: RFC Usage
 
 # RFC Usage
 
+The IETF RFC defiens two algorithms regarding HTTP headers and trailers, one to parse them and
+another one to serialize them.
+
 ## Parsing a field
 
-The first way to use the package is to enable HTTP header or HTTP trailer parsing. We will refer to them
-as HTTP fields for the rest of the documentation as it is how they are named in the IETF RFC.
+The package enabled HTTP header or HTTP trailer parsing. We will refer to them as HTTP fields
+for the rest of the documentation as it is how they are named in the IETF RFC.
 
 Let's say we want to parse the [Permissions-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#syntax) field. The first thing to know
 is that each structured field is defined against one specific data type which is
@@ -32,7 +35,7 @@ using the container public API:
 $permissions['picture-in-picture']->isEmpty(); // returns true because the list is empty
 count($permissions['geolocation']);            // returns 2 the 'geolocation' feature has 2 values associated to it via a list
 $permissions['geolocation'][-1]->value();      // returns the last value of the list 'https://example.com/'
-$permissions['camera']->value();               // returns '*' the sole value attached to the 'camera' feature
+$permissions['camera']->value()->toString();   // returns '*' the sole value attached to the 'camera' feature
 isset($permissions['yolo']);                   // returns false this permission does not exust
 $permissions->isEmpty();                       // returns false the dictionary contains some permissions
 echo $permissions;                             // returns 'picture-in-picture=(), geolocation=(self "https://example.com/"), camera=*'
@@ -42,8 +45,8 @@ echo $permissions;                             // returns 'picture-in-picture=()
 
 ## Serializing a field
 
-Conversely, if you need to quickly create a permission policy HTTP field text representation, the package
-provides the following ways to do by strictly following the RFC:
+Conversely, if you need to quickly create and serialize a permission policy HTTP field text representation, the package
+provides a serializer mechanism which strictly follow the RFC:
 
 ```php
 echo DataType::Dictionary->serialize([
@@ -54,14 +57,12 @@ echo DataType::Dictionary->serialize([
 // returns picture-in-picture=(), geolocation=(self "https://example.com/"), camera=*
 ```
 
-Again, we start from the knowledge that the field is a `Dictionary`, content is added using
-pairs to respect value position. As such we can turn the iterable construct we have into a
-proper HTTP field text representation by applying the serialization mechanism described in
-the RFC.
-
-While field building may look overwhelming, at first, it follows the fully described and tested
-process from the RFC. The package exposes numerous methods to simplify this process for you.
+Again, we start from the knowledge that the field is a `Dictionary`. The content is added
+using lists or ordered map represented as collection of pairs to respect value position.
+As such we can turn the iterable construct we have into a proper HTTP field text representation
+by applying the serialization mechanism described in the RFC.
 
-The goal of the examples are to show that even without dwelling too much into the ins and out
-of the package you can easily and quickly parse or serialize compliant fields in PHP base solely
-on the RFC.
+Because field building may look overwhelming, at first, the package exposes numerous methods to
+simplify this process for you. But nevertheless it is important to understand that even without
+dwelling too much into the ins and out of the package you can easily and quickly parse or
+serialize compliant fields in PHP base solely on the RFC information.

docs/_layouts/default.html

@@ -12,7 +12,7 @@
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta name="description" content="{{ site.data.project.description }}">
-    <meta name="docsearch:version" content="{{ version }}">
+    <link rel="icon" href="{{ site.baseurl }}/assets/img/httpsf-logo.svg" type="image/svg+xml">
     <title>{{ page.title }} - {{ site.data.project.title }}</title>
     <link rel="apple-touch-icon-precomposed" href="//theme.thephpleague.com/img/apple-touch-icon-precomposed.png">
     <link rel="preconnect" href="https://fonts.googleapis.com">
@@ -25,6 +25,7 @@
     <header class="flex items-center sm:justify-center pl-6 pr-6 pb-6 max-w-7xl mx-auto pb-32">
         <div class="flex gap-6 md:gap-0 md:flex-row justify-between md:items-center p-3 md:p-6 w-full max-w-7xl">
             <a class="flex items-center gap-2 sm:gap-3" href="{{ site.baseurl }}/">
+                <img src="{{ site.baseurl }}/assets/img/httpsf-logo.svg" alt="Logo" class="w-[40px] sm:w-[50px] h-[40px] sm:h-[50px]"/>
                 <div class="font-black">HTTP Structured Fields</div>
             </a>
         </div>
@@ -82,6 +83,9 @@ <h3 class="font-semibold tracking-tight text-slate-900">Older versions</h3>
             <article class="content">
                 {{ content }}
             </article>
+            <div class="flex justify-center items-center">
+                <img src="{{ site.baseurl }}/assets/img/httpsf.svg" alt="Logo" class="w-[240px] sm:w-[250px] h-[80px] sm:h-[82px]"/>
+            </div>
         </div>
     </main>
     <footer class="p-6 max-w-7xl mx-auto pb-32">

docs/_layouts/homepage.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="description" content="{{ site.data.project.description }}">
-    <meta name="docsearch:version" content="4.0">
+    <link rel="icon" href="{{ site.baseurl }}/assets/img/httpsf-logo.svg" type="image/svg+xml">
     <title>{{ site.data.project.tagline }} - {{ site.data.project.title }}</title>
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -15,7 +15,10 @@
 <div class="relative z-10">
     <header class="flex items-center sm:justify-center">
         <div class="flex gap-6 md:gap-0 md:flex-row justify-between md:items-center p-3 md:p-6 w-full max-w-7xl">
-            <div class="flex items-center gap-2 sm:gap-3"></div>
+            <div class="flex items-center gap-2 sm:gap-3">
+                <img src="{{ site.baseurl }}/assets/img/httpsf-logo.svg" alt="Logo" class="w-[40px] sm:w-[50px] h-[40px] sm:h-[50px]"/>
+                <div class="font-black text-2xl">HTTP Structured Fields</div>
+            </div>
             <div class="flex items-center gap-0 md:gap-0">
                 <a href="{{ site.data.project.repository_url }}" class="px-2 py-2 sm:px-6 sm:py-3 font-black text-md text-black-50 hover:text-csv-dark hover:underlines whitespace-nowrap">SOURCE CODE</a>
                 <a href="{{ site.baseurl }}/{{ site.data.project.release_major }}/" class="px-2 py-2 sm:px-6 sm:py-3 text-md text-white bg-csv-base hover:bg-csv-dark transition-all whitespace-nowrap rounded">Documentation</a>
@@ -48,6 +51,9 @@ <h2 class="font-medium text-3xl text-light">Work with HTTP Structured Fields in
             <div class="flex flex-col gap-3 my-16 content">
                 {{ content }}
             </div>
+            <div class="flex justify-center items-center">
+                <img src="{{ site.baseurl }}/assets/img/httpsf.svg" alt="Logo" class="w-[240px] sm:w-[250px] h-[80px] sm:h-[82px]"/>
+            </div>
         </div>
     </main>
 

docs/_layouts/redirect.html

@@ -4,8 +4,9 @@
     <meta charset="utf-8">
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="docsearch:version" content="4.0">
     <meta name="description" content="{{ site.data.project.description }}">
+    <link rel="icon" href="{{ site.baseurl }}/assets/img/httpsf-logo.svg" type="image/svg+xml">
+    <title>{{ page.title }} - {{ site.data.project.title }}</title>
     <meta http-equiv="refresh" content="0; url={{ page.redirect.to }}">
     <title>{{ site.data.project.tagline }} - {{ site.data.project.title }}</title>
     <link rel="stylesheet"href="{{ site.baseurl }}{{ site.data.manifest['docs.css'] }}">
@@ -34,6 +35,9 @@ <h1>Redirecting…</h1>
         <article class="content">
             {{ content }}
         </article>
+        <div class="flex justify-center items-center">
+            <img src="{{ site.baseurl }}/assets/img/httpsf.svg" alt="Logo" class="w-[240px] sm:w-[250px] h-[80px] sm:h-[82px]"/>
+        </div>
     </div>
 </main>
 <footer class="p-6 max-w-7xl mx-auto pb-32">