Re: Relationship between doc directory and fontforge.github.io
Skef Iterum <[email protected]> Mon, 11 Feb 2019 05:13:02 -0800
| Newsgroups | gmane.comp.fonts.fontforge.devel |
|---|---|
| Message-ID | <[email protected]> |
This is a multi-part message in MIME format.
--===============2770737795275451191==
Content-Type: multipart/alternative;
boundary="------------0D379229FE0E114A75707F54"
Content-Language: en-US
This is a multi-part message in MIME format.
--------------0D379229FE0E114A75707F54
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 8bit
Suppose that the following were to happen:
1. The quality of the markdown -> HTML translation were improved to the
point that the output was at least as good as the native HTML in
doc/html.
2. The master copies of the Markdown files that have doc/html
equivalents were moved to doc/md or some such.
3. The files in doc/html were replaced with equivalent content
generated on the server-side from the markdown files, configured to
produce "freestanding" HTML that works directly in a browser.
4. doc/README.md were to ndicate that any updates be made to the
markdown files, and the push request checks updated to mark any
mismatches as errors.
5. The website generation scripts were reconfigured to pull those docs
from doc/md at release time and build website-appropriate output.
This arrangement could also be adapted to allow the website to have docs
for different releases, (potentially) at the cost of a loss of some
interlinking.
I'm guessing it would also be possible to provide some kind of
translation service for forks of the FontForge repository on Github. In
fact, I can imagine a system that automatically adds a commit with the
updated HTML documents to every push request, if anything in the doc
directory has changed. (That's a little aggressive, though. It might be
easier just to have some support to make the change and squash at merge
time.)
Would there be interest in this type of solution? I'm guessing the main
worry would be breaking doc compatibility with forks.
Skef
On 2/11/19 4:26 AM, T J wrote:
>
> There is in effect, no relationship. The doc folder may be included in
> bundled releases, depending on the package manager, but the website is
> fully controlled by updating
> http://github.com/fontforge/fontforge.github.io
>
> So if you wanted to sync the two, itd have to be done manually. Note
> that repo has both the new (markdown) files, but also a copy of the
> old (plain html) website, which probably more closely resembles the
> docs you find in the main repo. Theres probably a lot that could be
> done to improve on that.
>
> Jeremy
>
> ------------------------------------------------------------------------
> *From:* Skef Iterum <[email protected]>
> *Sent:* Monday, February 11, 2019 10:25:27 PM
> *To:* [email protected]
> *Subject:* [fontforge-devel] Relationship between doc directory and
> fontforge.github.io
> In my push requests that affected documentation I have made changes in
> the doc/html directory of the repository. The website repository has
> versions of those files in markdown. Can someone -- briefly, and at a
> high level -- walk me through the relationship between those two
> repository directories? No "judgment" is implied, I am just not sure
> whether I've missed some automated conversion script, or if the idea is
> to use a separate tool at release time, or just do a diff with the last
> release's commit and update manually.
>
> I'm interested in working on some of the items in meta/TODO.md --
> particularly the anchor problem. I don't yet know much about Jekyll but
> I'm pretty adept with Pandoc at this point. But I would benefit from
> some general issue of how the whole system is intended to work in
> relation to new releases.
>
> Skef
>
>
>
> _______________________________________________
> fontforge-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/fontforge-devel
> http://fontforge.10959.n7.nabble.com/Developer-f3.html
>
>
> _______________________________________________
> fontforge-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/fontforge-devel
> http://fontforge.10959.n7.nabble.com/Developer-f3.html
--------------0D379229FE0E114A75707F54
Content-Type: text/html; charset=windows-1252
Content-Transfer-Encoding: 8bit
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=windows-1252">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>Suppose that the following were to happen:</p>
<ol>
<li>The quality of the markdown -> HTML translation were
improved to the point that the output was at least as good as
the native HTML in <tt>doc/html</tt>.</li>
<li>The master copies of the Markdown files that have <tt>doc/html</tt>
equivalents were moved to <tt>doc/md</tt> or some such. <br>
</li>
<li>The files in doc/html were replaced with equivalent content
generated on the server-side from the markdown files, configured
to produce "freestanding" HTML that works directly in a browser.</li>
<li><tt>doc/README.md</tt> were to ndicate that any updates be
made to the markdown files, and the push request checks updated
to mark any mismatches as errors. <br>
</li>
<li>The website generation scripts were reconfigured to pull those
docs from <tt>doc/md</tt> at release time and build
website-appropriate output. <br>
</li>
</ol>
<p>This arrangement could also be adapted to allow the website to
have docs for different releases, (potentially) at the cost of a
loss of some interlinking. <br>
</p>
<p>I'm guessing it would also be possible to provide some kind of
translation service for forks of the FontForge repository on
Github. In fact, I can imagine a system that automatically adds a
commit with the updated HTML documents to every push request, if
anything in the <tt>doc</tt> directory has changed. (That's a
little aggressive, though. It might be easier just to have some
support to make the change and squash at merge time.) <br>
</p>
<p>Would there be interest in this type of solution? I'm guessing
the main worry would be breaking doc compatibility with forks. <br>
</p>
<p>Skef<br>
</p>
<div class="moz-cite-prefix">On 2/11/19 4:26 AM, T J wrote:<br>
</div>
<blockquote type="cite"
cite="mid:SYAPR01MB304049DD59610A82CFDA895AC2640@SYAPR01MB3040.ausprd01.prod.outlook.com">
<meta name="Generator" content="Microsoft Exchange Server">
<div lang="EN-AU">
<div class="x_WordSection1">
<p class="x_MsoNormal">There is in effect, no relationship.
The doc folder may be included in bundled releases,
depending on the package manager, but the website is fully
controlled by updating
<a href="http://github.com/fontforge/fontforge.github.io"
moz-do-not-send="true">http://github.com/fontforge/fontforge.github.io</a></p>
<p class="x_MsoNormal"> </p>
<p class="x_MsoNormal">So if you wanted to sync the two, itd
have to be done manually. Note that repo has both the new
(markdown) files, but also a copy of the old (plain html)
website, which probably more closely resembles the docs you
find in the main repo. Theres probably a lot that could be
done to improve on that.</p>
<p class="x_MsoNormal"> </p>
<p class="x_MsoNormal">Jeremy</p>
<p class="x_MsoNormal"> </p>
</div>
<hr tabindex="-1">
<div id="x_divRplyFwdMsg" dir="ltr"><b>From:</b> Skef Iterum
<a class="moz-txt-link-rfc2396E" href="mailto:[email protected]"><[email protected]></a><br>
<b>Sent:</b> Monday, February 11, 2019 10:25:27 PM<br>
<b>To:</b> <a class="moz-txt-link-abbreviated" href="mailto:[email protected]">[email protected]</a><br>
<b>Subject:</b> [fontforge-devel] Relationship between doc
directory and fontforge.github.io
<div> </div>
</div>
</div>
<span>
<div class="PlainText">In my push requests that affected
documentation I have made changes in
<br>
the doc/html directory of the repository. The website
repository has <br>
versions of those files in markdown. Can someone -- briefly,
and at a <br>
high level -- walk me through the relationship between those
two <br>
repository directories? No "judgment" is implied, I am just
not sure <br>
whether I've missed some automated conversion script, or if
the idea is <br>
to use a separate tool at release time, or just do a diff with
the last <br>
release's commit and update manually.<br>
<br>
I'm interested in working on some of the items in meta/TODO.md
-- <br>
particularly the anchor problem. I don't yet know much about
Jekyll but <br>
I'm pretty adept with Pandoc at this point. But I would
benefit from <br>
some general issue of how the whole system is intended to work
in <br>
relation to new releases.<br>
<br>
Skef<br>
<br>
<br>
<br>
_______________________________________________<br>
fontforge-devel mailing list<br>
<a class="moz-txt-link-abbreviated" href="mailto:[email protected]">[email protected]</a><br>
<a
href="https://lists.sourceforge.net/lists/listinfo/fontforge-devel"
moz-do-not-send="true">https://lists.sourceforge.net/lists/listinfo/fontforge-devel</a><br>
<a
href="http://fontforge.10959.n7.nabble.com/Developer-f3.html"
moz-do-not-send="true">http://fontforge.10959.n7.nabble.com/Developer-f3.html</a><br>
</div>
</span>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<pre class="moz-quote-pre" wrap="">_______________________________________________
fontforge-devel mailing list
<a class="moz-txt-link-abbreviated" href="mailto:[email protected]">[email protected]</a>
<a class="moz-txt-link-freetext" href="https://lists.sourceforge.net/lists/listinfo/fontforge-devel">https://lists.sourceforge.net/lists/listinfo/fontforge-devel</a>
<a class="moz-txt-link-freetext" href="http://fontforge.10959.n7.nabble.com/Developer-f3.html">http://fontforge.10959.n7.nabble.com/Developer-f3.html</a>
</pre>
</blockquote>
</body>
</html>
--------------0D379229FE0E114A75707F54--
--===============2770737795275451191==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
--===============2770737795275451191==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
_______________________________________________
fontforge-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/fontforge-devel
http://fontforge.10959.n7.nabble.com/Developer-f3.html
--===============2770737795275451191==--