progit2
progit2 copied to clipboard
progit
Please make the diagrams with open source tools
The source file for the diagrams requires a commercial/non-free application that is only available on OSX.
We know this. If you happen to know somebody who has this application and can export the pictures to SVG for instance, please proceed.
Searched and found some free alternatives (gratis, unfortunately not open source) which can open Sketch files and export SVGs:
I can at least confirm they each imported and rendered, but I didn't do much beyond that. Only issue I saw was that it tries to use the Menlo-Regular and Menlo-Bold fonts, which seem to be Mac-only.
I tried Figma and Lunacy. They does not fully support Sketch file. For example:
After using Lunacy, I realized the reason why using Sketch file is there are some components are common in use, I mean the Symbols feature .
That could be a huge reason.
Think about changing the color of following symble:
=> 
and figure changes:
And all figures using it will be able to benefit from it.
So, I am not sure it is good to use SVG?
use the Menlo-Regular and Menlo-Bold fonts, which seem to be Mac-only.
True. And I replace the font with Bitstream Vera Sans Mono. (cf. https://github.com/progit/progit2/issues/605#issuecomment-464557332)
Why are we not crafting SVGs?
On Wed, Mar 13, 2019, 06:18 Yue Lin Ho [email protected] wrote:
Note: Lunacy 3.14
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/progit/progit2/issues/1158#issuecomment-472283450, or mute the thread https://github.com/notifications/unsubscribe-auth/AHTnkfHwzruFsEwHwtOVB74p6lx3nTfkks5vWIo9gaJpZM4Z7q3w .
That could be a huge reason. Think about changing the color of following symble:
Factorization of common attributes is perfectly doable in SVG. But, there are great chances that the extracted SVGs would be "flattened" (i.e. every element embeds all its attributes) and we would loose the ability to change the styling.
@YueLinHo could you provide the output svg so that we can check its structure?
Factorization of common attributes is perfectly doable in SVG.
Nice! ^__^
@YueLinHo could you provide the output svg so that we can check its structure?
OK. Will try it later. :-)
@YueLinHo As you wrote correctly, the font used is licensed from Apple and not generally available. The font you suggested, "Bitstream Vera Sans Mono," is not suitable for normal typesetting. It is not a proportional font but a monospaced font, which is better suited for texts that should represent a code text. In continuous text, the typeface appears broken because the letter spacing is not harmonious. (See https://www.fontsquirrel.com/fonts/bitstream-vera-sans-mono).
If you're looking for a free font that is similar to the one in the Sketchbook file and whose license also allows free commercial use, you'll find some alternatives e.g.: https://www.fontspace.com/vincenzo-vuono/gravity or https://www.fontspace.com/kineticplasma-fonts/falling-sky. In addition, the Google Fonts are copyright free (See https://fonts.google.com/?category=Sans+Serif).
@jnavila As I don't have a Mac available at the moment, I have to open the progit.sketch file with Lunacy (v4.0.3). Assuming it is displayed correctly, I, as a graphic designer, immediately notice some "don'ts", which considerably reduce the display quality of the images. On the browser page and in the PDF file, the images appear to me rather blurred. I don't understand how this can happen with a vector drawing program like Sketch. Apparently a serious error may have occurred in the workflow.
The initiator of the issue has suggested to use open source software to create the images. From my point of view Inkscape (https://inkscape.org/) would be suitable for this task, it is available for OSX, Windows and Linux. It is also vector-based and you can create your own symbol library, so that a unified design of the images is possible. A small "HowTo" should be enough to explain the workflow to the various authors. If you like, I can create a new branch in my fork and give some examples for discussion.
@max123kl the files included in both media are png (the way they were extracted from Sketch), and they were heavily compressed. Keeping the format in vector shapes would provide better as long as it is suitable for web pages and PDF. SVG is such format.
Inkscape manipulates SVG files, so this would be great. The problem is that up to now, the exports from Sketch were very lousy. Please go ahead with some sample, and if it can be integrated, you could even better provide a full conversion of the images. :+1:
It does not make sense to reconstruct existing images by duplicating the work. In addition, the check for content errors must be carried out again afterwards.
I suggest that we first analyze where the error hides in the workflow and then focus on eliminating it. As I said I don't have a Mac and the Sketch tool as well, so at the moment I can only refer to the output of the Windows Lunacy tool. Therefore I can only refer to the output of the Windows Lunacy program at the moment. In other words, I'm pretty sure – what I see here isn't what Sketch produces.
In Sketch's online manual, the section "File Formats" (https://www.sketch.com/docs/exporting/file-formats/) explains that data export to PNG, but also to SVG and EPS is possible. It would be very helpful if you could save two images ("local" and "branch-and-history") and the symbol part in SVG and EPS formats respectively. I especially hope for a lot from the EPS format, as it is universally used in professional image processing. You can send the files to my e-mail address or place them in the "diagram-source" folder.
Regardless of what I said before, I immediately noticed when looking at the progit.sketch file that the constructed diagrams on the individual pages are no longer in vector format, but in bitmap format. Images in vector format can be enlarged losslessly, the quality of the bitmap format decreases, which is particularly noticeable in typefaces. The images of the *.PNG files in the ./Images folder are almost all 800 px wide. The same figure (local.png) in the progit.sketch file has only 335 px, so it has to be enlarged more than twice. This leads to a significant blur. In addition, they were extremely compressed and also indexed (the color space of the images was reduced from 24 bit to 256 colors). Subsequent sharpening is no longer possible. Vector files can usually be edited afterwards without loss of quality, which also means that the effort to improve the images would be considerably less, if the data were available in vector format without indexing.
Another question about the symbols and the symbol library in the Sketch file: Should it also be possible to edit the text within the symbol in the future? At the moment I can't do that - but it can also be a faulty Lunacy output.
@jnavila I have reconstructed some symbols with Inkscape. I have saved the work in four different file variants (https://github.com/max123kl/progit2-de/tree/Figures/diagram-source) The file test_oneA.svg and test_oneB.svg contains the graphics in original size, whereas ...A.svg was saved as normal SVG and ...B.svg as "optimized SVG" (reduced color gamut). The files test_oneAx2.svg and test_oneBx2.svg contain the graphics in approx. 2.6x magnification. The size of the ...Bx2 file is larger than that of the ...Ax2 file. I have to check this again. But if the result should be confirmed I see no reason to reduce the color gamut to get a smaller memory size. What can be clearly seen is that the image quality did not suffer due to the magnification.
You see two columns, on the left side I have stayed as close as possible to the original. In the right column I made some small changes. So I lightened or darkened the text a bit to increase the contrast, which improves the readability. In the first row I placed two small color fields behind the graphics in the middle to simulate the background color on the website and the Sketch program. At the right graphic I made the filling color a bit darker to increase the contrast.
OK, I've finally been able to load up the source file in the Sketch editor – I had tried a while ago, and it kept crashing on me. Here's what I understand as the desired outcome:
- Change the diagram font. I'm thinking Roboto Mono here, but I'm open to suggestions. Would something else be better for ebook download sizes?
- Export the diagrams as SVG, and use those in the build path for ebooks.
- Keep some kind of method for updating diagram styles en masse. Sketch provides this, but is there a way to export so that "symbols" are usable in something like Inkscape?
Does that sound correct?
The first part of this will be accomplished in https://github.com/progit/progit2/pull/1285.
I'm interested in the SVG export. If it's flattened, then it's not really useful for future changes, but if they export a structured file (with styles and reused groups) it could be used as our primary source for images.
Sadly it doesn't seem to include links back to anything like Sketch "symbols". It looks like we'll have to start from zero if we want that, and I'm not sure what tool would be best for it. Maybe we could use a trial to import into Gravit?
The rendering is good. There's no style, but the resulting size is still lower. Even in this state, it should bring better images.
@ben I don't think Gravit can be the solution, because the features of the Community Edition aren't enough to move the project forward. The price of the Pro Version seems to be moderate, but it has to be paid per year and it is not in the sense of Open Source. But the more serious reason, for me, is that another cloud service is trying to get user data.
- Keep some kind of method for updating diagram styles en masse. Sketch provides this, but is there a way to export so that "symbols" are usable in something like Inkscape?
Inkscape can define symbols and combine and save them in a library. Since I mainly use the Adobe Design programs in my job, I can't make a more precise statement now. My first attempt in this direction showed that the created symbol has smaller dimensions than the artwork when placed in a drawing, but this can be a matter of setting. Another effect is that texts contained in it cannot be edited (my current state of knowledge). Since I don't know how the workflow is organized, I can't judge if this is a problem. If necessary, this has to be solved by a workaround (perhaps via scrip). To my knowledge, Sketch can export its drawings as SVG. Inkscape can import SVG. It would be worth a try to put a Sketch export file in ./diagram-source, so that you can start a test on how the switch can work (preferably automatically).
@jnavila Since English is not my first language, please specify what you mean by this:
If it's flattened, then it's not really ... There's no style, but ...
I don't really understand your workflow yet. Which functions/options are essential for a smooth workflow?
@ben
Change the diagram font. I'm thinking Roboto Mono here, but I'm open to suggestions.
I can't understand the reason why it has to be a monospaced font in the diagrams. A proportional font is much easier to read —> Roboto (not Mono) For code examples, a monospaced font is better. The font should then be more different from the base font and not belong to the same font family (e.g. FreeMono)
@max123kl
When you work with files, you usually define custom styles (colors, width, color gradients, fonts...) for shapes and texts that you can refer to in all your designs. This allows to enforce a single look&feel.
These styles are usually saved in you design file in native format, but when you export to another format, the styles are most of the time "applied" to each shape. Then if you wish to modify the style, on the exported files, you have to modify each part individually, because they no longer refer to a unique shared style definition. Additionally, adding new elements requires to copy/paste the style from another part instead of applying the common style.
Here, from what I see, in the SVG, The shapes no longer refer to a single style (see it as a pyramid with all shapes pointing at the style above them). Here each shape has it's own definitions. That's what I call "flattened", because there's no longer any entity above them.
@jnavila My problem is that I can't access Sketch, so I can't check for myself if an export to SVG leads to a solution. As YueLinHo already described in his first post here, Lunacy cannot read the progit.sketch file without errors. Therefore, my idea is to get a true copy of the design via Sketch-SVG-Export —> Inkscape-SVG-Import. Then I can check if Inkscape can build a style and shape library that can be used as a basis for future diagrams, just like Sketch does now. As such a library exists and is loaded into Inkscape the styles should be recognized and assigned. I think this link describes the desired function. Please take a look into a Sketch SVG file with a plain text editor. The structure should look similar to my test file and not like my export example. In the first case, the design is defined as paths that can be edited later; in the second case, the design is embedded as a bitmap image in the SVG file, which is unchangeable. So if Sketch produces a clean XML code, I see a good chance to solve the problem. Then you should also be able to edit the artwork when re importing to Sketch.
Please take a look into a Sketch SVG file with a plain text editor.
Over in #1285 I've done the SVG export from Sketch. Is this what you'd consider a "good" SVG? If so, I'll merge that PR and we can go from there, but we don't need to necessarily accomplish all of these goals in a single PR.
I can't understand the reason why it has to be a monospaced font in the diagrams.
Most of the text in the diagrams is things like SHA-1 hashes, ref names, and the content of blobs, so a monospace font makes sense there. I'd be open to switching the descriptive labels to a proportional font in the future, but the goal right now is to remove the dependencies on Menlo and Sketch.
@ben I have downloaded the named file and: That looks good What I have to criticize from a typographic point of view is the unprofessional use of an outline with such a small font. I had seen this before, but hoped it was a converting error. I have corrected this with Inkscape exemplarily at a field and provided a screenshot. At the time I made this the Roboto Mono font was not yet installed. Therefore you can see in this picture the fonts Menlo Regular and Bold (at the bottom). In the optical comparison the Bold (at the bottom) looks a bit lighter than what you have published so far (at the top). I then installed Roboto Mono and took another screenshot of the same field. Simultaneously I chose another monospaced font in the field below, which offers more font weights than the Roboto (see list left of the middle). This could be an alternative if Roboto Mono Bold is too thin for you. This font is calles Source Code Pro and also free for commercial use (see website).
OK, if these SVGs seem like a good starting point, I'm going to merge that PR. Then we'll be free to experiment with fixing things wholesale before we start using SVGs for the diagrams in ebook builds.
OK, fine We should first try to build the symbol library. The required SVG should be easy to export. When that is done, several authors can work on the images.
I found a nice, illustrated tutorial here. Unfortunately only in German, but not much text and very simply written, so that an automatic translator should have no problem with it. It also describes how a symbol library can be created, edited and passed on to others.
BTW: I just found another page where you can adjust the font size and other features with CSS code, maybe it helps. This works best with Open Type Fonts (OTF), a newer font format. The often used True Type Font format (TTF) offers much fewer options. All used fonts so far are TTF's (see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/OpenType_fonts_guide).
I just looked at the first file. Do you really want to use an outline of 1px with a font of only 9pt? This almost damages the font more than the old setting.
Much more important is to change the color of the filling from black (000000ff) to gray (979797ff), the outline color. Then the ugly black spots disappear in the font. The best unit of measurement for fonts is Point (pt). You can see how to do this in the screenshot. Note the active, lighter tabs.
Change the font weight from Regular to Bold. Then, I recommend a maximum outline of 0.3 pt for a font size like this of 9 pt (note the lowercase "a").
Edit: I just edited the file advance-master.svg according to my recommendation.
That was just a raw export from Sketch. I’m happy to review a PR that
removes the stroke from all the text elements in the SVGs.
On Mon, Aug 5, 2019 at 3:57 PM Dieter Ziller [email protected] wrote:
I just looked at the first file. Do you really want to use an outline of 1px with a font of only 9pt? This almost damages the font more than the old setting.
Much more important is to change the color of the filling from black (000000ff) to gray (979797ff), the outline color. Then the ugly black spots disappear in the font. The best unit of measurement for fonts is Point (pt). You can see how to do this in the screenshot https://github.com/max123kl/progit2-de/blob/Figures/diagram-source/tests/Font_weight.svg. Note the active, lighter tabs.
I recommend a maximum outline of 0.5 pt for a font size like this of 9 pt (note the lowercase "a").
— You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/progit/progit2/issues/1158?email_source=notifications&email_token=AAAJXXWX3MT5465MACBQGFDQDCV4LA5CNFSM4GPOVXYKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD3TKH3A#issuecomment-518431724, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAJXXUS6V4YV7GSEUCPEZDQDCV4LANCNFSM4GPOVXYA .
--
– Ben
That was just a raw export from Sketch. I’m happy to review a PR that removes the
strokefrom all the text elements in the SVGs.
Can you tell me files that contain this "stroke"? I can't find any. Or do you mean the black flashes I spoke of, inside the characters? How to remove them, I had described in my last post.
I would like to bring in my thoughts about the choice of fonts and their modifications.
The principle Form Follows Function was originally developed in architecture and industrial design. Today, however, it should also be applied in communication science. In simple words: According to Marshall McLuhan, in communication everyone is both sender and receiver of information. If you want an information offer (e.g. a book) to be accepted by the recipient, you have to choose a form that makes it easy for the reader to consume it. Here "Form Follows Function" is back in the game. The readability of texts, together with a logical and optically easy to understand structure, is a fundamental element in the communication mix. The advertising industry has been using this principle for decades successfully.
In order to transfer my thoughts to this project, it would mean choosing fonts and techniques that are helpful for the intended goal.
I understand that the numerous fonts make it difficult for anyone who is confronted with them to make a good decision.
I would like to take back my previous statement (see quote).
I recommend a maximum outline of 0.3 pt for a font size like this of 9 pt (note the lowercase "a").
For reasons of readability and aesthetics, fonts smaller than 36 pt should not be used with any outline larger than 0 pt. Because there are so many fonts, it is possible to find a more suitable alternative that meets your personal needs.
I have modified the file advance-master.svg again and placed it in the /diagram-source/tests folder so that it can be compared with the latest version. I have included some different fonts that I think are suitable to be used here. I made sure that the license says: "Permission is hereby granted, free of charge ..."
I would prefer an OTF font, because it offers better features, as I wrote before. I made my selection from the this search query
Can you tell me files that contain this "stroke"? I can't find any.
Sure, here's one of the text nodes from the SVG file I linked to above:
<text id="master" stroke="#979797" stroke-width="1" font-family="RobotoMono-Regular, Roboto Mono" font-size="12" font-weight="normal" fill="#000000">
<tspan x="24.9970703" y="21">34ac2</tspan>
</text>
Note the stroke="#979797" stroke-width="1" properties. I think if those are removed you won't see the outlining you (rightly) disapprove of. Here's a snippet from your linked SVG:
<text
id="master"
font-size="12"
font-weight="normal"
style="font-weight:normal;font-size:12px;font-family:RobotoMono-Regular, 'Roboto Mono';fill:#000000;stroke:#979797;stroke-width:0.4;stroke-miterlimit:4;stroke-dasharray:none">
<tspan
style="stroke-width:0.4;stroke-miterlimit:4;stroke-dasharray:none;-inkscape-font-specification:'Roboto Mono, Bold';font-family:'Roboto Mono';font-weight:bold;font-style:normal;font-stretch:normal;font-variant:normal;font-size:12px;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;fill:#979797;fill-opacity:1"
x="24.994141"
y="21"
id="tspan11">f30ab</tspan>
</text>
Here the outline is coming from the style property, where stroke-width:0.4 will force an outline.
Oh, and regarding the choice of font for the diagrams: if Roboto Mono is not acceptable, I'm completely happy with Source Code Pro.