From 8d92065b86d7631a2960c37eff9ffd847e30626f Mon Sep 17 00:00:00 2001 From: constantinos Date: Wed, 12 Jul 2023 02:00:07 +0300 Subject: [PATCH] uploaded Info issue --- content/article/infrastructure.md | 45 +++ content/article/markdown-formatting.md | 363 +++++++++++++++++++++++++ content/article/print-cite.md | 42 +++ content/article/sample-article.md | 112 ++++++++ content/article/submission-guide.md | 31 +++ content/issue/issue-journal-info.md | 13 + content/print/p-everything.md | 8 + content/print/p-issue-journal-info.md | 7 + 8 files changed, 621 insertions(+) create mode 100644 content/article/infrastructure.md create mode 100644 content/article/markdown-formatting.md create mode 100644 content/article/print-cite.md create mode 100644 content/article/sample-article.md create mode 100644 content/article/submission-guide.md create mode 100644 content/issue/issue-journal-info.md create mode 100644 content/print/p-everything.md create mode 100644 content/print/p-issue-journal-info.md diff --git a/content/article/infrastructure.md b/content/article/infrastructure.md new file mode 100644 index 0000000..c05e398 --- /dev/null +++ b/content/article/infrastructure.md @@ -0,0 +1,45 @@ +--- +title: "About this infrastructure: Sandpoints" +date: "2023-06-29T18:35:24+03:00" +author: "anybody" +contributors: ["constantinos-miltiadis.md"] +draft: false +keywords: + - journal info +--- + +This project implements *Sandpoints*, an open source framework for open and collaborative publishing. It is developed by Marcell Mars since 2019, and built as a theme for the static website builder [Hugo](https://gohugo.io/). Both *Hugo* and *Sandpoints* are free, open source, and cross platform, and are developed in the programming language *Go*. + +Key features: +1. *Sandpoints* requires no programming. +2. Creating new content and compiling a website project are done with simple terminal commands. +3. Content is added with ![Markdown files](article:markdown-formatting), which are easy to read, write, and edit, and organized in folders by type. +4. *Sandpoints* implements hypertext, including backlinks (bidirectional hyperlinks), and allows non-linear content traversal, for example via browsing links, backlinks, and keywords. +5. *Sandpoints* is structured around a triadic hierarchy, here this is *Journal>Issue>Article*, or: + ``` + Journal + └── Issue + └── Article + ``` +6. Collaboration, version control, and backup are achieved via Git. +7. *Sandpoints* projects are fully portable. They can be viewed as online webpages, copied and +8. *Sandpoints* can generate printable and interactive PDFs for its content (for individual entries, issues, or all the content; see [print](/print/)) . +9. *Sandpoints* allows for integration with a library catalogue. The library is accessible at [Library](/library/BROWSE_LIBRARY.html), or by pressing the red icon at the top-right corner of any page. + +The implementation of *Sandpoints* in academic research publishing was outlined by van Gerven Oei in the editorial of *Dotawo* Journal issue 7 (2020): + +> Starting with the present issue, _Dotawo_ will design and publish its content via the [Sandpoints](https://git.sandpoints.org/UnionForNubianStudies/Dotawo) platform. _Dotawo_ contributions are formatted in [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax, thus moving away from proprietary software such as Microsoft Word and Adobe InDesign. For collaboration and version-control we employ [Git](https://en.wikipedia.org/wiki/Git) rather than Google Drive or Dropbox. The online issue is created via [Gitea](https://gitea.io/en-us/) and [Hugo](https://gohugo.io/), which take the Markdown files from the Git repository and generate a static website from them. The result is a compact and fast website, which moreover can also be used offline. Also the typography of _Dotawo_ is now based on open fonts. The journal is typeset in [Gentium](https://software.sil.org/gentium/), which is released under an [SIL Open Font License](http://scripts.sil.org/ofl). The PDF output is generated by [PagedJS](https://www.pagedjs.org/) [...]. In short, all of the software used in the creation of _Dotawo_ is now open source. Although this process demands a certain amount of flexibility of the editors, it also shows that transitioning an open access journal to open infrastructure is not only possible but also feasible.[^vincent] + +[^vincent]: [Preface by the Editor (Vincent W.J. van Gerven Oei, Dotawo issue 7, 2020)](https://pages.sandpoints.org/dotawo/issue/dotawo7/). + + +Flagship *Sandpoints* projects include: +- The academic journal [Dotawo -- A Journal of Nubian Studies](https://pages.sandpoints.org/dotawo/journal/) (since issue 7, 2020), +- [Machine listening](https://machinelistening.exposed/curriculum/) , and +- [Pirate.care](https://syllabus.pirate.care/) (that uses on a different visual theme). + + +# Notes +- For an extended description of *Sandpoints* see [Sandpoints Portfolio (sandpoints.org)](https://pages.sandpoints.org/sandpoints/simplesandpoints-de47f813/draft/portfolio/), which includes descriptions of its implementation in different projects, and related bibliography. +- [Sandoints (Gitea project repository)](https://git.sandpoints.org/Drawwell/). +- See also Graziano, Valeria, Marcell Mars, and Medak Tomislav. ‘Learning from \Syllabus’. In _State Machines: Reflections and Actions at the Edge of Digital Citizenship, Finance, and Art_, edited by Yiannis Colakides, Marc Garrrett, and Inte Gloerich. Amsterdam: Institute of Network Cultures (Amsterdam, 2019. [http://www.statemachines.eu/books/state-machines-reflections-and-actions-at-the-edge-of-digital-citizenship-finance-and-art/](http://www.statemachines.eu/books/state-machines-reflections-and-actions-at-the-edge-of-digital-citizenship-finance-and-art/). \ No newline at end of file diff --git a/content/article/markdown-formatting.md b/content/article/markdown-formatting.md new file mode 100644 index 0000000..147dc14 --- /dev/null +++ b/content/article/markdown-formatting.md @@ -0,0 +1,363 @@ +--- +title: "Markdown formatting guide" +date: "2023-06-28T01:58:32+03:00" +author: "anybody" +contributors: ["constantinos-miltiadis.md"] +draft: true +keywords: + - draft +abstract: | + This is a Markdown formatting guide. +--- + +# What is Markdown + +Markdown is an open standard for a flexible, human-readable, lightweight mark-up language for formatting text. It was developed by John Gruber and the late Aaron Swartz, and released in 2004. Markdown files have the extension ‘*.md*’ and consist of plain text. Therefore Markdown files can be opened, edited and ready using any text editor, rudimentary or otherwise. + +Since its release Markdown was adopted widely for multiple applications. For example by *GitHub* (for readme files), by R (as R Markdown), for note-taking and collaborative writing (e.g. *Obsidian*, *hackmd.io*, *Zotero*, *Nextcloud*), for chat applications (e.g. *Element*), and also by static website frameworks (e.g. *Hugo* and *Jekyll*). + +Although one can write in Markdown in a rudimentary notepad, it is recommended to use a text editor such as [Obsidian](https://obsidian.md/), or [Visual Studio Code](https://code.visualstudio.com/.). For an online Markdown editor see [hackmd.io](https://hackmd.io/). +For further resources on Markdown see [notes](#notes). + +# Markdown formatting guide + + +## Writing in Markdown +Markdown is a plain text format, intended for digital text. +It's unlike conventional word processors that simulate writing on paper and follow the what-you-see-is-what-you-get (WYSIWYG) concept. + +Markdown is intended to facilitate writing and reading. + +em dash -- with some content inside -- is useful. + +*Formatting:* +``` +This will +appear as +a single +line. +``` + +*Appearance:* +This will +appear as +a single +line. + +## Text formatting + +| Formatting | Appearance| +|-|-| +|`normal text`| normal text| +| `*emphasis*`| *emphasis*| +| `**bold**`| **bold**| +| `***bold emphasis***`| ***bold emphasis***| +| `~~strikethrough~~`| ~~strikethrough~~| +| \`code blocks\`| `code blocks`| +| `somethingsuperscript` | somethingsuperscript| +| `somethingsubscript` | somethingsubscript | +| `\* \~ \[ \{ \#` | \* \~ \[ \{ \#| + +## Headings + +Headings make use of the hashtag character, as follows: + +``` +# Heading +## Sub-heading +### Sub-sub-heading +``` +Note that a space is required between the hashtag character and the header text. + +## Lists + +Markdown bullet lists use the dash/minus symbol as in: +``` +- bullet item +``` + +Numbered lists start with a number followed by a period as in: +``` +1. list item +``` + +Note that both cases require a space before the list item text. +To add depth, add two spaces or a tab in a subsequent list item. + +### Bullet lists + +Bullet list formatting: +``` +- bullet 1 +- bullet 2 + - sub-bullet 2.1 +``` +Bullet list appearance: +- bullet 1 +- bullet 2 + - sub-bullet 2.1 + +### Numbered lists + +Numbered list formatting: +``` +1. List item 1, +2. List item 2, + 1. Sub-item 2.1 +``` + +Numbered list appearance: +1. List item 1, +2. List item 2, + 1. Sub-item 2.1 + +## Quotes + +*Blockquotes:* +> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010). + +*Blockquote formatting:* + +``` +> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010). +``` + +*Inline quotes:* +For shorter quotes, use inline quotes, between "quotation marks" and should be followed by a reference (Author 2015). + +Note that: +- > If *you emphasized some text yourself you need to mention that in the reference* (Author et al. 2010; emphasis mine). +- > Or if your quote includes an *emphasis found in the original* (Author et al. 2020, emphasis in original). +- If your inline quote includes a world + +- [how to mention 'et al.' : Author and colleagues or Author et al.?] + + + + + +- [example of normal in-line quote] +- [omitting author from ref] Discussing x, Author described that "this is a good case of" (2010). +- [example of quote edit] +- [example of transcript] +- [example of emphasis] + +## Images + +Recommended and supported image formats are: +- PNG for rasterized content. +- SVG for vector content. +Avoid image formats that are lossy and can introduce artifacts (e.g. JPG). + +*Image formatting pseudocode*: +``` +![](path/to/image.png) +**Figure 1**: Caption text. +``` + +*Image formatting example*: +``` +![](static/sample/jgdr-test-illustration.svg "Optional mouse-over text. Figure 1: Sample illustration in SVG.") +**Figure 1: Sample illustration in SVG.** + +![](static/sample/jgdr-test-illustration-3x.png "Optional mouse-over text.") +**Figure 2: Sample illustration in PNG** +``` + +*Appearance*: + + +![](static/sample/jgdr-test-illustration.svg "Optional mouse-over text. Figure 1: Sample illustration in SVG.") +**Figure 1**: Sample illustration in SVG (vector format). +![test](static/sample/jgdr-test-illustration-3x.png "Optional mouse-over text. Figure 2: Sample illustration in PNG.") +**Figure 2**: Sample illustration in PNG (raster format); exported from Illustrator: type-optimized, transparent background, size x3. + +## Tables + +*Table formatting*: +``` +| Header 1 | Header 2 | Header 3| +|--|--|--| +| This | is | a| +| table | with | content.| +``` + +*Table appearance*: +| Header 1 | Header 2 | Header 3| +|--|--|--| +| This | is | a| +| table | with | content.| + +Note: The number of dashes in the second row is arbitrary + +--- + +In case alignment is important, it can be assigned per column. + +- *Formatting*: +``` +| Header 1 | Header 2 | Header 3| +|:--|:--:|--:| +| left | center | right| +``` + +- *Appearance*: + +| Header 1 | Header 2 | Header 3| +|:--|:--:|--:| +| left | center | right| + + +For a table without headers, leave the initial row empty. + +- *Formatting*: + +``` +| | | +|-|-| +|A|table| +|without|headers| +``` + +- *Appearance*: + +| | | +|-|-| +|A|table| +|without|headers| + +## Hyperlinks + +- *Hyperlink formatting*: + +``` +[hyperlink caption](https://hyperlink-destination.org) +``` + +- *Hyperlink appearance*: + +[hyperlink caption](https://hyperlink-destination.org) + +Note: Do not omit the `http://` or `https://` part of the URL. + +## Internal Links + +To link to another section of the same document, use the hyperlink syntax. +For destination use the heading of the section, in lowercase, replacing spaces with dashes. Prefix that with only one hashtag character, regardless of the depth of the heading. + +Formatting example (a link to the first section of this document): +[go to 'What is Markdown'](#what-is-markdown). + +Syntax: +``` +[go to 'What is Markdown'](#what-is-markdown) +``` + + +## Footnotes + +The syntax for inserting a footnote is `[^key]`, where `key` can be arbitrary. The content of the footnote can be placed anywhere in the document, and follows the syntax `[^key]: Footnote content.` + + +Here is a sentence with a footnote.[^fn] Footnotes are placed *after* a period or comma, like here.[^fn] Footnotes can be reused, and Sandpoints will generate dynamic backlinks to all mentions of the same footnote.[^fn] + +[^fn]: This is the text of a footnote, used 3 times. + +Formatting: + +``` +Here is a sentence with a footnote.[^fn] +[^fn]: This is the text of a footnote, used 3 times. +``` + +## Embedded content + +Hugo can embed a range of different media via shortcodes (see [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/)). Note that embedded media cannot be exported to PDF or printed. +More importantly, + + +YouTube, and Vimeo videos can be easily embedded using video ids (the last bit of their URLs). Embedded content should contain a caption including... + + +{{< youtube UEoDJ1v6U6U >}} +**Video 1**: Video caption. + +{{< vimeo 55073825 >}} +**Video 2**: Video caption. + +Formatting (replace square brackets with curly brackets): +``` +[[< youtube UEoDJ1v6U6U >]] +**Video 1: Description.** + +[[< vimeo 55073825 >]] +**Video 2: Description.** +``` + + +### GitHub Gists + +{{< gist cmiltiadis 0c458dcea8b8569398f5988b0151636c >}} + +Formatting (replace square brackets with curly brackets): +``` +[[< gist username gistId >]] +``` + +### Videogame embedding + +Implement Unity WebGL embed described here: +https://michaelcassidy.net/post/hugo-shortcode-for-embedding-unity-webgl-players-updated-with-code/ + +This should allow embedding games as follows (note: square brackets need to be replaced with curly brackets): +``` +> [[< unity-webgl-player game +> Title="My cool game" +> width="1024" height="576" +> buildURL="https://somewhere.com/path/to/files/Build" +> buildFileName="webgl" +> playerID="" >]] +``` +## Unused formatting + +The following includes formatting that might be useful while writing, but has limited application in published material. + +### Horizontal dash + +Formatting +``` +--- +``` + +Appearance + +--- +Note: Leave an empty line before a horizontal dash. + +### Toggle lists + +- [ ] Unchecked toggle item. +- [x] Checked toggle item. + +``` +- [ ] Unchecked toggle item. +- [x] Checked toggle item. +``` + +### Comments + +To comment out some content, so that it's ignored use HTML comment formatting as follows: +``` + + + +``` + + +# Notes +- For the original Markdown specification see [Markdown specification (John Gruber, 2004)](https://daringfireball.net/projects/markdown/). +- For a Markdown formatting guide see [Basic Syntax (markdownguide.org)](https://www.markdownguide.org/basic-syntax/). \ No newline at end of file diff --git a/content/article/print-cite.md b/content/article/print-cite.md new file mode 100644 index 0000000..0eb1219 --- /dev/null +++ b/content/article/print-cite.md @@ -0,0 +1,42 @@ +--- +title: "Save PDFs & Cite" +date: "2023-06-29T22:19:04+03:00" +author: "anybody" +contributors: ["constantinos-miltiadis.md"] +draft: false +keywords: + - journal info +abstract: | + Instructions for saving printable PDFs and for citing contributions. +--- + + +# Save interactive and printable PDFs + +- To browse printable content see [print](/print/). +- Using [Chrome](https://www.google.com/chrome/), open any of the 'print' type content. +- *Sandpoints* will dynamically generate a printable PDF. For larger collections, *Sandpoints* might need a few seconds to typeset the document and populate the table of contents. +- In Chrome go to File/Print (or press `ctr+P` or `cmd+P`). +- Click Save the PDF in the pop-up dialogue. + +The exported PDFs include internal hyperlinks () + +Note, media content are not included in PDFs. + +# Cite contributions + +- Will share a Zotero Translator (citation grabber) in time, which we can push to the Zotero Translator repo. + +Related metadata: + +| Fields | Value | +|--|--| +| Publication name | *Journal name*| +| Journal abbreviation | *--*| +| ISSN | *get one* | +| Publication date | *implement* | +| author | automated | +| issue | automated | +| abstract | automated | +| keywords | automated | +| URL | automated | diff --git a/content/article/sample-article.md b/content/article/sample-article.md new file mode 100644 index 0000000..9ee1ad7 --- /dev/null +++ b/content/article/sample-article.md @@ -0,0 +1,112 @@ +--- +title: "Sample Article" +date: "2023-06-30T00:36:18+03:00" +author: "anybody" +contributors: ["jane-contributor.md"] +draft: false +keywords: + - sample article + - journal info +abstract: | + The text of your abstract. Max length..? +--- + +# Introduction + +This is a sample article for submissions. +Contributions are natively processed in Markdown format. For a guide about writing in Markdown see ![Markdown guide](article:markdown-formatting). +However, one can also submit in conventional word processor formats (DOCX, ODT). + +# Submission sample package + +[Download submission sample](/sample/dummy-package/dummy-package.txt). + +# Main fields + +## Title +> ! Capitalization conventions? + +## Abstract +Abstract is to be included in the header file. +If the submission is not provided in Markdown format, clearly mark and place the Abstract *before* the introductory heading of your article. + +## Keywords +Add three keywords at minimum. + +# Article body + +## Headings + +Use up to three levels of headings. + +> ! Heading capitalization? + +## Tables + +| Header 1 | Header 2 | Header 3 | +| - |- | - | +| Item 1 | Item 2| Item 3| +| Item 5 | Item 6| Item 7| + +Table 1: Sample table. + +## Images + + +Supported image formats are: +- SVG (vector) +- PNG (raster) +- JPG (raster; lossy, thus not preferred) + +Place graphics in a subfolder e.g. `graphics/`. + +> - What identifier to use ? (Figure / Image/ Graphic?) +> - !Images should appear **before/after** the first mention, and should be referred to in full, as in Figure 1 (not fig. 1). + +![](static/sample/jgdr-test-illustration.svg) +**Figure 1: Sample illustration in SVG (vector format).** + +![](static/sample/jgdr-test-illustration-3x.png) + +**Figure 2: Sample illustration in PNG (raster format); exported from Illustrator; type-optimized; transparent background; size x3.** + +Markdown formatting: +``` +![](static/sample/jgdr-test-illustration.svg) +**Figure 1: Sample illustration in SVG.** + +![](static/sample/jgdr-test-illustration-3x.png) +**Figure 2: Sample illustration in PNG.** +``` + +# Citations + +We recommend the use of [Zotero](https://www.zotero.org/). + +> Citation style: Chicago? + +## Quotes + +> Block quotes are used for quotations that are 40 words or more, and are followed by a reference (Author 2015). + +For shorter quotations, use in-line quotes, as in "this is a quotation" (Author 2015). + +# Conclusion + +Checklist: +- [ ] Consistent use of EN/US English. +- [ ] Submission has been proof read. +- [ ] Included graphics are provided in a subfolder. +- [ ] The contribution is anonymized. + +Submit a zip file including: +- A Markdown file of the article. +- Bibliography included in the Markdown file, or in extra `.bib` file. +- A folder including all images (e.g. `graphics`). +- Provide necessary artifacts + - via link to drive, repository, or + - include them in full as `zip` files. + +# References + + diff --git a/content/article/submission-guide.md b/content/article/submission-guide.md new file mode 100644 index 0000000..aebed58 --- /dev/null +++ b/content/article/submission-guide.md @@ -0,0 +1,31 @@ +--- +title: "Submission Guide" +date: "2023-06-24T15:21:59+03:00" +author: "anybody" +draft: true +keywords: + - journal info +abstract: | + Submission guide. +--- + + \ No newline at end of file diff --git a/content/issue/issue-journal-info.md b/content/issue/issue-journal-info.md new file mode 100644 index 0000000..e94148a --- /dev/null +++ b/content/issue/issue-journal-info.md @@ -0,0 +1,13 @@ +--- +title: "Journal Information and Submission Guide" +date: "2023-06-28T14:20:48+03:00" +author: "anybody" +draft: false +has_articles: ["infrastructure.md","submission-guide.md","sample-article.md", "markdown-formatting.md","print-cite.md"] +keywords: + - journal info +abstract: | + This is an issue providing information about the journal and submission information. +--- + +This issue provides information about the journal, its infrastructure, submissions, Markdown formatting, citing, ... \ No newline at end of file diff --git a/content/print/p-everything.md b/content/print/p-everything.md new file mode 100644 index 0000000..8ac5725 --- /dev/null +++ b/content/print/p-everything.md @@ -0,0 +1,8 @@ +--- +title: "Print Whole Journal" +date: "2023-06-29T18:50:00+03:00" +author: "anybody" +draft: false +print: "journal/index.md" +--- + diff --git a/content/print/p-issue-journal-info.md b/content/print/p-issue-journal-info.md new file mode 100644 index 0000000..91cf552 --- /dev/null +++ b/content/print/p-issue-journal-info.md @@ -0,0 +1,7 @@ +--- +title: "Journal Info Print" +date: "2023-06-29T22:53:09+03:00" +author: "anybody" +draft: false +print: "issue/issue-journal-info.md" +---