How to chisel at chiselapp.com

Difference between version 4 and 5 - Previous - Next
<<inlinehtml>>

<style>
img {
  filter: drop-shadow(0 0 6px black);
    -webkit-border-radius: 4px;
    -moz-border-radius: 4px;
    border-radius: 4px;
}
ap {
    color: #0000FF;
    font-family: times;
}
</style><h1 id="how-to-chisel-at-chiselapp.com">How to chisel at chiselapp.com</h1>
<p>The excellent <a href="https://www.fossil-scm.org">Fossil SCM</a> is so distinguished against the general background (most often for the better) that it is incomprehensible why this system is still underestimated in the IT community.</p>
<p>In question is not the quality of Fossil - it is the highest - but the ways of presenting it. And it’s here the issues come.</p>
<p><em>The issue #0</em>.</p>
<p>The software behemoths can only support those VCS that can satisfy their behemothic appetites. As a result, those VCS are delivered to every home as “a must”. Though you need to be behemoth to use those VCS in full.</p>
<p>So, it’s a real issue for those tended to be behemothic.</p>
<p>If you are not a behemoth and have no desire to become of this type, you can easily do without those fat meals served for begemoths. It means less dependence, less ‘learning curve’, less headache. It means more mobility, more time, more health. It means you can do it with Fossil SCM.</p>
<p>So, it’s a zero value issue for those tended to be non-behemothic.</p>
<p><em>The issue #1</em>.</p>
<p>The originality of Fossil necessarily leads to the original terms and approaches, which is reflected in the documentation. Not to mention the fact that this documentation leaves much to be desired, because of:</p>
<ul>
<li>a lot of duplicates at the cluttered (permuted) <a href="https://www.fossil-scm.org/home/doc/trunk/www/permutedindex.html">Fossil Docs Index</a> that was obviously designed to make it easy, but resulted in making it hard</li>
<li>the diversity of terminology that is often duplicated as well</li>
<li>scarce, if any, manuals about samples of workflow with Fossil</li>
<li>no comprehensive all-inclusive guide in the public domain (the <a href="http://www.fossil-scm.org/schimpf-book/home">book by Jim Schimpf</a> is outdated and incomplete, alas)</li>
</ul>
<p><em>The issue #2</em>.</p>
<p>Many Fossil fans are looking for a place to apply their fossil skills and often find it at <a href="http://chiselapp.com">chiselapp.com</a> - a hosting service that is good in almost all respects - where, however, you don’t find a word about “how to chisel at chiselapp.com”.</p>
<p>Result: at <a href="http://chiselapp.com">chiselapp.com</a> there are a lot of started and abandoned projects (named test*), as well as a bunch of quite good, but not quite presentable projects. As a rule, projects have no home nor documentation nor download page. Illustrative stuff (pictures, videos) is missing or scarce.</p>
<p>There is nothing to say about <a href="http://chiselapp.com/repositories/">Public Repositories</a>. No sectioning, no structure, no filter by author. Although there is sorting by author but the project names go first at that. You must remember an exact name of author or resort to Ctrl+F. There are other shoals at <a href="http://chiselapp.com">chiselapp.com</a> that you need at least to know about.</p>
<p>These were the reasons of this document.</p>
<p><br><br></p>
<h2 id="contents">Contents</h2>
<p>Step by step, from registration to some customization, this document will discuss the creation of a site at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<blockquote>
<p><a href="#reg">0. Registration</a></p>
</blockquote>
<blockquote>
<p><a href="#create">1. Creating a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#dash">2. Dashboard</a></p>
</blockquote>
<blockquote>
<p><a href="#config1">3. Initial configuration</a></p>
</blockquote>
<blockquote>
<p><a href="#home">4. Home page</a></p>
</blockquote>
<blockquote>
<p><a href="#repocont">5. Contents of a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#skin">6. New skin</a></p>
</blockquote>
<blockquote>
<p><a href="#clone">7. Cloning a repository</a></p>
</blockquote>
<blockquote>
<p><a href="#dl">8. Pushing to chiselapp.com</a></p>
</blockquote>
<blockquote>
<p><a href="#crdoc">9. Documentation page</a></p>
</blockquote>
<blockquote>
<p><a href="#media">10. Pictures and videos</a></p>
</blockquote>
<blockquote>
<p><a href="#uvpage">11. Unversioned files and Download page</a></p>
</blockquote>
<blockquote>
<p><a href="#others">12. Customization</a></p>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#chperm">12.1 Changing permissions</a></p>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<p><a href="#chskin">12.2 Changing a skin</a></p>
</blockquote>
</blockquote>
<p><br></p>
<hr />
<p><br></p>
<p id="reg">
</p>
<h2 id="registration">0. Registration</h2>
<p>At <a href="http://chiselapp.com">chiselapp.com</a> you register as follows:</p>
<ul>
<li><em>Create Account</em> - create your account and register.</li>
</ul>
<p>or</p>
<ul>
<li><em>Log in</em> - register under your account.</li>
</ul>
<p>I would recommend to open a separate tab of browser at registering. You have no one-click way to return to <a href="http://chiselapp.com">chiselapp.com</a> from your repository.</p>
<p>Why? Sometimes you would have to repeate <em>Log in</em>. It’s <a href="http://chiselapp.com">chiselapp.com</a>, no toys.</p>
<p>To work with two repositories, you can try to log-in twice in two different browser windows. For example, you can run <em>chromium</em> and try “Open link in incognito window” of popup menu.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="create">
</p>
<h2 id="creating-a-repository">1. Creating a repository</h2>
<p>Let’s say we are logged in with <strong><a href="http://chiselapp.com/user/aplsimple">aplsimple</a></strong> account to create <strong><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a></strong> repository.</p>
<p>After <em>Log in</em>, click on <em>Create Repository</em> to create a new repository.</p>
<p>You get:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/create.png /></p>
<p>Enter:</p>
<p><em>Repository name</em> - repository name, <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/index">HOWTO_chisel</a>.</p>
<p><em>Repository password</em> - password to access the repository: although optional, it is better to enter your own.</p>
<blockquote>
<blockquote>
<p>It is important to note that the user password and the password for administrative access to the site are different ones. I always set a hard password for registering at Chisel, a hard password for accessing <em>public</em> repositories and an easy password for accessing <em>private</em> repositories.</p>
</blockquote>
</blockquote>
<p><em>Make this repository private</em> - I highly recommend enabling this option, because <strong>the site is not yet ready for publication</strong>. A private repository can be made public at any time. After all, our blunders will be visible only to us, and the public can wait.</p>
<p><em>Override project code</em> - leave this field blank, everything works without it.</p>
<p><em>Use SHA3 for initial commit</em> - you can enable it if the fossil version (by <em>fossil version</em> command) is newer or equal to 2.0; it’s for more protection against hacking.</p>
<p>Let’s click on <em>Create repository</em> and get the repository with the address:</p>
<ul>
<li>http(s)://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</li>
</ul>
<p>which means that our <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> repository will be available through one of the addresses:</p>
<ul>
<li><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">chiselapp.com/user/aplsimple/repository/HOWTO_chisel</a></li>
<li>http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</li>
<li>https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel</li>
</ul>
<p>Click <em>Return to dashboard</em>. It’s your own Chisel headquarters.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="dash">
</p>
<h2 id="dashboard">2. Dashboard</h2>
<p>See the <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> line in <em>Dashboard</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/dash.png /></p>
<p>where you have the options:</p>
<ul>
<li><p><em><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a></em> - to enter the repository</p></li>
<li><p><em>Edit</em> - to publish the site and to set a new password for administrative access; useful if you did not set a password for the repository (then fossil will create its own) or just forgot the password to access the site.</p></li>
<li><p><em>Remove</em> - to remove the repository</p></li>
<li><p><em>How to Clone</em> - for copy-paste of the cloning command</p></li>
</ul>
<p>For now, click on <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> to enter the repository .</p>
<p><br></p>
<hr />
<p><br></p>
<p id="config1">
</p>
<h2 id="initial-configuration">3. Initial configuration</h2>
<p>Having entered our repository, we are looking for the <em>Admin</em> tab. If it is not visible, then we need to log in the repository.</p>
<p>Click <em>Login</em> and enter your username (User ID) and password <em>for the site</em>. If you can’t log in, you need to return to <a href="#dash">Dashboard</a> and change the password for accessing the repository, through <em>Edit</em>.</p>
<p>It happens that when switching from one repository to another it is not possible to log in - then you need to <em>re-login</em> at <a href="https://chiselapp.com">chiselapp.com</a>, i.e. log out and log back in. This is <strong>a glitch of chiselapp.com</strong>.</p>
<p>When we first enter the repository, Fossil offers to set the initial configuration by clicking on <em>setup/config</em> - this is what we will do:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/config.png /></p>
<p>After clicking on <em>setup/config</em>, you have the following options:</p>
<ul>
<li><p><em>Project Name</em> - the name of the project (<a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>).</p></li>
<li><p><em>Project Description</em> - a brief description of the project.</p></li>
<li><p><em>Tarball and ZIP-archive Prefix</em> - a prefix for zip/tarball files; if left blank, <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> (project name) is used.</p></li>
<li><p><em>Download Tag</em> - leave <em>trunk</em> unchanged for now (the setting will come in handy in the future when <em>stable releases</em> would be downloaded).</p></li>
<li><p><em>Enable WYSIWYG Wiki Editing</em> - you may leave this option blank to edit <em>markdown</em> without fuss with html.</p></li>
<li><p><em>Index Page</em> - it is better to leave this option unchanged as <em>home</em>; generally, you can also specify <em>/doc/tip/index.wiki</em> or <em>/doc/tip/index.md</em>, as Fossil points out; but this will mean that the home page will coincide with the documentation page, which is not good, as home is home and the docs are the docs.</p></li>
<li><p>The following settings are important:</p>
<ul>
<li><em>Documentation Index</em> - link to the Documentation page</li>
<li><em>Download</em> - link to the Download page</li>
<li><em>License</em> - link to the License page</li>
<li><em>Contact</em> - link to the Contact page</li>
</ul></li>
</ul>
<blockquote>
<blockquote>
<blockquote>
<p>To publish or not your contacts is your own decision. The contacts can be in some README as well.</p>
</blockquote>
</blockquote>
</blockquote>
<blockquote>
<blockquote>
<blockquote>
<p>But <em>Documentation Index, Download</em> and <em>License</em> must be filled. Without docs and downloads, no one needs your software. And without a license, you lose potential users - those who have heard/faced enough of the EULA stories.</p>
</blockquote>
</blockquote>
</blockquote>
<p>I fill in the links like this:</p>
<ul>
<li><em>Documentation Index</em> - /doc/DOC/doc/index.md</li>
<li><em>Download</em> - /download</li>
<li><em>License</em> - https://www.gnu.org/licenses/gpl-3.0.txt</li>
</ul>
<p>The <em>/download</em> link at chiselapp.com will display the standard download and cloning page. For simple projects like <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>, it makes no sense to invent anything else. But if you want, you can specify <em>/uv/download.html</em> and get <a href="#uvpage">your own Download page</a> at chiselapp.com.</p>
<p>The <em>Documentation</em> link uses a Fossil feature called <em>embedded documentation</em>. More about this <a href="#crdoc">below</a>.</p>
<p>The <em>License</em> link may be external to the project, as in this case. Or it can be set as <em>/doc/DOC/doc/LICENSE.md</em> - i.e. as part of the same <a href="#crdoc">embedded documentation</a>.</p>
<p>At last, a <em>License</em> link may look like this:</p>
<ul>
<li>https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/artifact/b4d7662bb6b0b804</li>
</ul>
<p>or like this:</p>
<ul>
<li>/artifact/b4d7662bb6b0b804</li>
</ul>
<p>This is a link to a specific version of LICENSE.txt from your project. It’s easy to get it from the <em>Files</em> tab: right-click on <em>Files</em>/LICENSE.txt and select <em>Copy link address</em>. If LICENSE.txt is updated, you will need to update this link using <em>Admin / Configuration</em>.</p>
<p>Done with settings.</p>
<p>Ignore the <em>Use HTML as wiki markup language</em>.</p>
<p>Save the changes by clicking on <em>Apply Changes</em>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="home">
</p>
<h2 id="home-page">4. Home page</h2>
<p>It’s time to think about the look of our site at chiselapp.com.</p>
<p>Let’s log in our <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> repository to get administrator rights.</p>
<p>Then, open the <em>Wiki</em> tab and click on <em><a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> project home page</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/home.png /></p>
<blockquote>
<p><strong>Note</strong>: It happens you don’t see <em>YOUPROJECT project home page</em> in the Wiki page. In such case, you should choose <em>List of All Wiki Pages</em> either from Wiki tab or from the ☰ (hamburger button). Your Home page (in Wiki) has the same name as your project. If it is missing, create a <em>new wiki page</em> named as your project.</p>
</blockquote>
<p>In the upper panel, select <em>Edit</em> to enter the contents of Home page.</p>
<p>Fossil will stubbornly offer its own <em>Fossil Wiki</em> markup format. It is simple and convenient, but still it’s better to choose the standard <em>Markdown</em> from the <em>Markup style</em> drop-down list.</p>
<p>Markup rules are available right on the <em>Wiki</em> tab (Formatting rules for <em>Fossil Wiki</em> and for <em>Markdown Wiki</em>).</p>
<p>Enter your page. You can use the preview ( Preview Your Changes ).</p>
<p>When the page is ready, click on <em>Apply These Changes</em>. Check how it works using the <em>Home</em> tab. We repeat all over again if there are problems.</p>
<p>There are tons of great programs that you can use to create and preview markdown documents. For example, <a href="http://github.com/wereturtle/ghostwriter">ghostwriter</a>. But the final version must still be checked at <a href="http://chiselapp.com">chiselapp.com</a>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="repocont">
</p>
<h2 id="contents-of-a-repository">5. Contents of a repository</h2>
<p>Now let’s look inside our repository.</p>
<p>Click on the <em>Timeline</em> tab. You will see something like:</p>
<pre><code>1 check-in
2019-09-01
     09:59  [9cf295d8d7] Leaf: initial empty check-in (user: aplsimple tags: trunk)</code></pre>
<p>The <ap><code>tags: trunk</code></ap> is important - it sets the name of the main branch. This is the main content of this initial commit.</p>
<p>There may be confusion in [terms] (https://www.fossil-scm.org/home/doc/trunk/www/checkin_names.wiki). There are synonyms for some terms and different meanings (by context) for others.</p>
<p>The <strong>tip</strong> means the last commit made, while the <strong>trunk</strong> means not the commit, but the name of the main branch starting from the first commit created by <em>fossil init</em>. As a rule (but not always), <em>tip</em> is on <em>trunk</em> and as such in commands they mean the same. Hence the confusion. If the last commit is not made on the main branch, <em>tip</em> and <em>trunk</em> refer to different commits.</p>
<p>There are terms that are not used in commands, but are often used in the documentation:</p>
<ul>
<li><strong>check-in</strong> , <strong>checkin</strong>, <strong>version</strong> - a commit</li>
<li><strong>check-out</strong>, <strong>checkout</strong> - a commit that determines the state of the working directory</li>
<li><strong>leaf</strong> - a last commit of branch; if a branch is specified in the fossil command instead of a commit, it means <em>leaf of the branch</em></li>
</ul>
<p><strong>checkout</strong>, <strong>co</strong> is <em>fossil</em> command as well.</p>
<p>Special commit names:</p>
<ul>
<li><strong>current</strong> - current check-out or leaf of the current branch (in <em>update, checkout</em> commands )</li>
<li><strong>next</strong> - next commit (child of the current)</li>
<li><strong>prev</strong>, <strong>previous</strong> - previous commit (parent of the current)</li>
</ul>
<p>When we left the <em>trunk</em> value unchanged in <a href="#config1">Download Tag</a> setting, we indicated to Fossil that zip/tarball will be downloaded from the top (leaf) of this main branch.</p>
<p>If the main branch is under development and you want to publish the previous stable version, you can specify the tag of this version in the <em>Download Tag</em> setting (for example, <ap>v1.0</ap>).</p>
<p>The repository having been started, now it remains to clone it. Do not waste time looking for the cloning command in the <em>default skin</em>. Of course, you will find it - either in the <a href="#dash">Dashboard</a> or in <em>Admin / Configuration</em>, but you must be an administrator to do this. Users will not see the Download page in the default skin. Another <strong>shoals of chiselapp.com</strong>.</p>
<p>So, we should set up a site skin where the Download page (and the cloning command) is easily accessible.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="skin">
</p>
<h2 id="new-skin">6. New skin</h2>
<p>We select the <em>Admin</em> tab, then find and choose <em>Skins</em>.</p>
<p>In the <em>Skins</em>, we skip all initial words and go to the end of page, where we click on <em>Skin Admin</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/skin1.png /></p>
<p>In the open list of skins, select to install the first one, i.e. Default <em>Install</em>.</p>
<p>Now the Download page is easily accessible from the ☰ (hamburger button):</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/skin2.png /></p>
<p><br></p>
<hr />
<p><br></p>
<p id="clone">
</p>
<h2 id="cloning-a-repository">7. Cloning a repository</h2>
<p>Let’s click on the ☰ hamburger button, then find and click <em>Download</em> in the <em>Home Page</em> list . The Download page will open, where we copy our cloning command:</p>
<pre><code>fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel  clone.fossil</code></pre>
<p>Instead of <code>clone.fossil</code> you can set your path to a future repository file. I prefer to store local Fossil repositories in the ~/FOSSIL directory, while the repository name is the same as the project name, i.e. my cloning command looks like this:</p>
<pre><code>fossil clone https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>But before any actions with repositories on the local machine, you should take care of the very important option of Fossil.</p>
<p>This is <strong>autosync</strong>, meaning automatic synchronization with the remote repository when committing. By default, it is turned on, which means that our commits will be automatically pushed to our chiselapp.com repository and other commits will be pulled. It only works great when we’re always online.</p>
<p>If we are only sporadically connected to the Internet, then we should switch the auto-synchronization off. Also, the auto-synchronization may not be liked by those who do not want all blunders to be visible on the network.</p>
<p>We disable the auto-synchronization with the command:</p>
<pre><code>fossil settings --global autosync 0</code></pre>
<p>Then we execute the cloning command:</p>
<pre><code>fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>getting the response from fossil:</p>
<pre><code>admin-user: apl (password is &quot;123456&quot;)</code></pre>
<p>where the password for administrative access to the repository is indicated. We must replace it with the command:</p>
<pre><code>fossil user password apl -R ~/FOSSIL/HOWTO_chisel.fossil</code></pre>
<p>You should enter <strong>the same repository access password</strong> that you set at chiselapp.com. If the password changes in the future, you will simply repeat this command.</p>
<p>So, the repository has been cloned. Now we go to the source directory of <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a>. Suppose we have already some files made in this directory, then our actions will be as follows:</p>
<pre><code>cd ~/projects/HOWTO_chisel
fossil open ~/FOSSIL/HOWTO_chisel.fossil
fossil addremove</code></pre>
<p>Thus, in the project directory <em><sub>/projects/HOWTO_chisel<em>, we initialized the fossil workflow with our local repository </em></sub>/FOSSIL/HOWTO_chisel.fossil</em>.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="dl">
</p>
<h2 id="pushing-to-chiselapp.com">8. Pushing to chiselapp.com</h2>
<p>Having worked a bit on our project, having accumulated a bunch of small commits in it, we decide to upload our stuff to chiselapp.com.</p>
<p>If the <a href="#clone">described above</a> <code>fossil settings autosync</code> is 1 (i.e. we always synchronize with the remote repository), then we have nothing to worry about. Our commits are already at chiselapp.com, we just go to Chisel and look at results.</p>
<p>However, if <code>fossil settings autosync</code> returns 0 (auto-synchronization is disabled), then periodically after committing it is necessary to download/upload commits from/to chiselapp.com, i.e. operate in an ordinary cycle: <em>pull / update / merge / commit / push / ..local changes</em>.</p>
<p>For example, the <code>push</code> command looks like this:</p>
<pre><code>cd ~/projects/PROJECT
fossil push https://USER:[email protected]/user/USER/repository/PROJECT</code></pre>
<p>where USER and PASS should be replaced with your username and password.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="crdoc">
</p>
<h2 id="documentation-page">9. Documentation page</h2>
<p>If our documentation is a simple README.md, we can easily create <em>Documentation</em> page.</p>
<p>We enter <em>Admin / Configuration</em> and fill in <em>Documentation</em> option like this:</p>
<pre><code>/doc/trunk/README.md</code></pre>
<p>This means that README.md of the root project directory would be taken from the main branch of the repository and displayed in the Documentation page. The fossil feature called <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> come in handy here.</p>
<p>So when we click the ☰ tab and then click on <em>Documentation</em>, we get our README.md converted to html.</p>
<p>But what if the documentation should be maintained this way:</p>
<ul>
<li>the documentation sources are not in zip/tarball, though are in the repository (with all their history)</li>
<li>only the generated documentation is in zip/tarball</li>
<li>the documentation is developed on a separate branch</li>
<li>the generated documentation is viewed with ☰ / <em>Documentation</em></li>
</ul>
<p>Answer:</p>
<p>The initial commit’s artifact of our repository is <a href="#repocont">[9cf295d8d7]</a>. We will branch from it to the new DOC branch and check-out it:</p>
<pre><code>fossil branch new DOC 9cf295d8d7
fossil co DOC</code></pre>
<p>Then we create a bunch of <strong>source</strong> documentation files.</p>
<p>Usually, one makes a separate <code>embedded</code> subdirectory in the project root:</p>
<pre><code>embedded/www
embedded/man
embedded/man/files
embedded/man/...</code></pre>
<p>Then one runs a kind of documentation generator that compiles <code>embedded/man</code> sources to <code>embedded/www</code> html pages .</p>
<p>We will also create the sources and generate documentation, then we will commit and return to the main branch. At the same time, we will sort the source and generated documentation files into <strong>different branches</strong> - DOC and trunk.</p>
<p>We will continue to operate on the main branch and commit - this is necessary so that our main trunk branch comes forward in the timeline. If you want to <em>push</em> right away, make an empty commit.</p>
<p>See details here (<em>4files</em> converts <em>md</em> -&gt; <em>html</em> which is unnecessary - it sets only an example of use):</p>
<ul>
<li><p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/2DOC">2DOC bash file</a></p></li>
<li><p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/2trunk">2trunk bash file</a></p></li>
<li><p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/4files">4files bash file</a></p></li>
<li><p><a href="https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/4files.tcl">4files.tcl</a></p></li>
</ul>
<p>So, after <em>pushing</em> the commits to chiselapp.com, make a change in the settings of <em>Admin/Configuration</em>:</p>
<ul>
<li><em>Documentation Index</em> - /doc/trunk/embedded/www/index.html</li>
</ul>
<p>or</p>
<ul>
<li><em>Documentation Index</em> - /doc/trunk/embedded/www/toc.html</li>
</ul>
<p>The <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> is good primarily for compiling docs before committing the result.</p>
<p>When we run <em>fossil ui</em> on the local machine and look at our documentation at:</p>
<blockquote>
<p>http://localhost:8080/doc/DOC/embedded/www/toc.html</p>
</blockquote>
<p>we will not see any changes in it until we commit, but committing what we have not seen is ridiculous. And here Fossil comes to the rescue: it is enough to replace the DOC (or standard trunk, if our docks are on the main branch) with <strong>ckout</strong>, i.e.</p>
<blockquote>
<p>http://localhost:8080/doc/<b>ckout</b>/embedded/www/toc.html</p>
</blockquote>
<p>and we will see the current uncommitted changes immediately (or after the generation of html).</p>
<p>This is how <a href="https://www.fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki">embedded documentation</a> works.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="media">
</p>
<h2 id="pictures-and-videos">10. Pictures and videos</h2>
<p>Adding a picture to Home page or Documentation page is as easy as adding a regular html page, because markdown files allow you to use most tags on static pages, in particular, the &lt;img&gt; tag.</p>
<p>Therefore, if <em>index.md</em> refers to certain image files, it is enough to copy all the images into a subdirectory under index.md (for example, <em>files</em>) and make all image links relative, for example:</p>
<blockquote>
<p>&lt;img src=“<ap>files/</ap>colorchooser1t.png” alt=“Tcl/Tk color picker changed” /&gt;</p>
</blockquote>
<p>The <a href="http://chiselapp.com/user/aplsimple/repository/pave/doc/DOC/doc/www/details.md">example of pave</a> was made this way.</p>
<p>The <a href="#home">Home page</a> is a bit more complicated, because it is created using regular chiselapp.com tools. If you need to include a picture in Home page, then where to find its address? Since the repository does not store files, but file artifacts, Home page should also link to image artifacts. For example:</p>
<blockquote>
<p>&lt;img src=“https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/raw/bb55ed2b9ca8d40f?m=image/png” /&gt;</p>
</blockquote>
<p>where bb55ed2b9ca8d40f - is the image artifact ID seen on the <em>Files</em> tab.</p>
<p>To find out the artifact of an image, you need to go to <em>Files</em> tab, find the image you need, click on it and go to the artifact page, then copy the artifact ID (for SHA3 it will be a rather long ID).</p>
<p>The same applies to other media resources stored in the repository.</p>
<p>But there is a preferred way to do this, when all binary resources are stored as one (unhistorical) version in the repository and the links to them look, for example, like this:</p>
<blockquote>
<p>&lt;img src=“http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/picture.png” /&gt;</p>
</blockquote>
<p>This method of storing data in the repository is discussed below.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="uvpage">
</p>
<h2 id="unversioned-files-and-download-page">11. Unversioned files and Download page</h2>
<p>An extremely useful feature of Fossil is storing files that have no history in the repository.</p>
<p>This thing is designed for creating download pages and, in general, for storing binary files. In the repository, the previous versions of binaries are most often not necessary. Moreover, they fatten the repository.</p>
<p>Once I tried to do <a href="https://aplsimple.github.io/en/tcl/e_menu/bin4hg.html">something similar</a> in Mercurial , as far as Mercurial allowed to do this. Then bitbucket.org <a href="https://bitbucket.org/blog/sunsetting-mercurial-support-in-bitbucket">‘sunsetted’ all the Mercurial people</a>. And then Fossil came to the rescue, and the problem was solved without crutches, elegantly and beautifully.</p>
<p>For full information, see <a href="https://www.fossil-scm.org/home/doc/trunk/www/unvers.wiki">Unversioned Files</a> .</p>
<p>Unversioned files’ best location is a directory excluded by <em>ignore-glob</em>:</p>
<pre><code>fossil settings ignore-glob .*,*~,*.swp,*.tmp,*.BIN,*.log</code></pre>
<p>Due to this, subdirectories like .BIN are excluded from the repository. They are not visible to all fossil commands, except for <em>fossil uv</em>.</p>
<p>Having our binaries in the .BIN subdirectory, we execute the command <em>uv add</em>:</p>
<pre><code>cd .BIN
fossil uv add *</code></pre>
<p>The trick is that <code>fossil uv add</code> will ignore the <em>ignore-glob</em> setting and mark all .BIN/* as unversioned files that will be updated at chiselapp.com with the command:</p>
<pre><code>fossil uv sync</code></pre>
<p>These files will be available on all pages of the site using the links like:</p>
<pre><code>http://chiselapp.com/user/USER/repository/PROJECT/uv/FILENAME</code></pre>
<p>For example:</p>
<pre><code>http://chiselapp.com/user/aplsimple/repository/pave/uv/pave.zip
http://chiselapp.com/user/aplsimple/repository/pave/uv/test2pave.mp4</code></pre>
<p>The similar links are available in <a href="#crdoc">Documentation</a> page(s).</p>
<p>Also, in the .BIN directory, you can create an “unofficial” download page.</p>
<p>If it is <em>download.html</em>, then the “unofficial” download page can be set in <em>Admin / Configuration</em> this way:</p>
<ul>
<li><em>Download</em> - /uv/download.html</li>
</ul>
<p>Just don’t forget the <a href="#clone">clone command</a> in your download page.</p>
<p><br></p>
<hr />
<p><br></p>
<p id="others">
</p>
<h2 id="customization">12. Customization</h2>
<br>
<p id="chperm">
</p>
<h3 id="changing-permissions">12.1 Changing permissions</h3>
<p>User <em>anonymous</em> has the right to modify the <em>Wiki</em>. It seems to be a good feature, but the problem is that <em>anonymous</em> can go this way:</p>
<ul>
<li>Home / List / <a href="http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel">HOWTO_chisel</a> / Append</li>
</ul>
<p>… to calmly write at the end of the <a href="#home">Home page</a> what he/she can only contrive. <strong>Another shouls of chiselapp.com</strong>.</p>
<p>In no way this should be allowed. Therefore, you must change the rights of <em>anonymous</em>.</p>
<p>We go to <em>Admin / Users</em>, select <em>anonymous</em> and cancel the <em>Append Wiki</em> right. After that, click on <em>Apply changes</em>:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/user.png /></p>
<br>
<p id="chskin">
</p>
<h3 id="changing-a-skin">12.2 Changing a skin</h3>
<p>We can slightly change the <a href="#skin">standard skin</a>.</p>
<p>Our task:</p>
<ul>
<li><p>Remove <em>Timeline</em> and <em>Branches</em> from the tab list.</p></li>
<li><p>Add <em>Docs</em> and <em>Download</em>.</p></li>
</ul>
<p>To do this, enter <em>Admin / Skins</em>.</p>
<p>We need to make changes to the settings:</p>
<ul>
<li>CSS</li>
<li>Header</li>
<li>Footer</li>
<li>Details</li>
<li>Javascript</li>
</ul>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin1.png /></p>
<p>It is important to remember that these settings <strong>may not match</strong> the <em>Default</em> skin, even if you select <em>Default (built-in)</em> in the <em>Initialize skin draft1 using</em>. There is <strong>some kind of glitch</strong> with this.</p>
<p>The proper settings can be taken from the Fossil website:</p>
<p><a href="https://fossil-scm.org/home/dir?ci=tip" class="uri">https://fossil-scm.org/home/dir?ci=tip</a></p>
<p>There you need to enter <em>skins/default</em> subdirectory, from where the contents of the files:</p>
<ul>
<li>css.txt</li>
<li>header.txt</li>
<li>footer.txt</li>
<li>details.txt</li>
<li>js.txt</li>
</ul>
<p>should be transferred to the mentioned settings, according to the names.</p>
<p>While making changes to these settings, you should pay attention that the <em>Edit SETTING for Draft1</em> form will open in a separate browser tab. After confirming the changes with the <em>Apply</em> button, you should close the tab to return to the <em>Skins</em> window.</p>
<p>In <em>Header</em>, changes are needed in two places:</p>
<p><ap> <strong>1)</strong> </ap></p>
<pre><code>menulink $index_page Home {}
if {[anycap jor]} {
    menulink /timeline Timeline {}
}</code></pre>
<p><ap>should be changed so:</ap></p>
<pre><code>menulink $index_page Home {}
menulink /doc/DOC/doc/index.md Docs {}
menulink /download Download {}
if {[anycap s]} {
    # jor
    menulink /timeline Timeline {}
}</code></pre>
<p><ap> <strong>2)</strong> </ap></p>
<pre><code>if {[hascap o]} {
    menulink  /brlist Branches desktoponly</code></pre>
<p><ap>should be changed so:</ap></p>
<pre><code>if {[hascap s]} {
    # o
    menulink  /brlist Branches desktoponly</code></pre>
<p>In short, the <em>Docs</em> and <em>Download</em> items have been added, and the access to <em>Timeline</em> and <em>Branches</em> has been changed so that these tabs are visible only to the administrator (they can still be accessed through the hamburger button ☰, but not through the tab bar).</p>
<p>After these changes made, turn on the options:</p>
<ul>
<li><em>Skin draft1 has been tested and found ready for production.</em></li>
<li><em>The current skin should be overwritten with draft1.</em></li>
</ul>
<p>and click on <em>Publish Draft1</em>.</p>
<p>Now users (and you when being not an administrator) will see only the necessary:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin2.png /></p>
<p>or:</p>
<p><img src=https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/chskin3.png /></p>
<p>For more on skins, see <a href="https://www.fossil-scm.org/home/doc/trunk/www/customskin.md">Skinning the Fossil Web Interface</a>.</p>
<hr />
<h3 id="to-be-continued">to be continued</h3>

<<inlinehtml>>

<<categories>> Application | Dev. Tools