TODO.taskpaper

mdtools 2.x:
	see ./proposal-for-mdtools-2.0.md for details (mostly outdated now...)
	Order of user stories is relevant for handling dependencies!
	This update will most likely break the deckset renderer and the reveal.js renderer pretty thoroughly.
	- first page and (page title in title tag of that link) is hardcoded in html-head.html, that should be a config variable and an entry in the translation memory 
- 	make sure texts for prev/next are  added to translation memory
	- bug: images zoom under menu
	- bug: zoomify/css: icons are not possible in index.html (or anywhere else in the content)
	- menu is not 100% wide on mobile
	- break in navigation buttons on mobile
	- fix vertical spacing in the text


	- fix gitHub page: 
		- all assets must must prepend baseurl (e.g. "/mdtools"): like so: {{ "/assets/style.css" | relative_url }} @done(22-02-24)
		- all links must know baseurl??? -> this must remain broken for now, because that means adding code in several places, and figuring out a way to handle local preview and publishing, maybe di that together with redirect and page structure that reflects the content structure?
	- section links could be lowercased before rendering???
	- check out how Javascript Tutorial handles translations of illustrations, they solve the exact same problem we do 
		https://github.com/javascript-tutorial/server
	- add a chapter in the docs about the enhancement of mdtools and move the enhancement proposal for 2.0 as well as large parts of this document there, and only keep this taskpaper for current projects and small things and bug tracking
	
	Cooler website (maybe later):
		- move menu icon to the right of next to site icons for moother mobile navigation @later
		- smaller headline and less spacing in header for better mobile view @later @done
		- search for patterns
		- theme picker (text size, white, sepia, dark theme) via session storage: https://javascript.info/localstorage
		- responsible map overlay.
		- keep menu open
		- look at https://javascript.info/websocket: has nice info boxes and a great searchable tutorial map 
			Links (botstrap etc.):
				matrial design for botstrap: https://mdbootstrap.com/ (probably not necessary)
				Menus in bootstratp 4:
					best practices: https://webdesign.tutsplus.com/articles/best-practices-for-responsive-dropdown-menus--cms-35212
					good explanation how to include bootstrap and inclue a menu (which is not layered, so other code would be required for that): https://medium.com/better-programming/an-introduction-to-using-jekyll-with-bootstrap-4-6f2433afeda9
					explanation of html/css for responsive menus (nav element and media queries): https://inspirationalpixels.com/creating-a-responsive-menu-with-html-css-jquery/
					
	MVP: Responsive Pattern Map:
		Macro Support: @estimate(30min)
			- variables:
					green: #FF0000
				{{name:$green}} or {{name:var(green)}}
			- test that variable-name can be correctly substituted in macros and templates (the cfg-object's key is "variable_name")
		Plugin and Macro Support: @estimate(8h)
			As developer I want a simple plugin API that allows for defining new macros, and access to the preprocessor for preparing required data structures so that I can easily add new behaviour with just a few lines of code
			- configure plugins globally and per document type
			- plugins used for a specific document can be configured globally or in the preset 
			- override and extend plugin list in document type
			- define parameters per plugin
			- add preprocessor plugins
			- refactor S3-specific macros to use plugin architecture
		Plugin for Clickable Pattern Map: @estimate(4h)
			As reader of the practical guide, I want a responsive patter map so that I can navigate effortlessly between patterns.
			- add plugin to create html for pattern map structure
			- add remplate and JS for pattern map
			- add css for pattern map
			- add texts to localization.pot if required 
		Release the practical guide: @estimate(2h)
			
	sync glossary with crowdin:
		https://realpython.com/api-integration-in-python/ 
		look at realpython 1/2 pdf
		use rest3client to abstract crowdin API https://pypi.org/project/rest3client/#description
		- get api token from crowdin.yaml
		- ensure glossary in crowdin is set up do distinguish between the followingentry types:
			- patterns
			- previous pattern names
			- pattern category
			- "synced" glossary entries
			- other stuff (probably best that this category has no markers)
		- sync patterns
			- ensure all current patterns are present, add those that are missing
			- ensure all everything else marked as pattern is now marked as obsolete
		- sync pattern category names
		- sync glossary entries 
			- ensure everythinh in glossary.yaml is present, update to the latest description (mark those that are no longer in glossary.yaml as obsolete)
			- test by copying the current glossary to a new project
			- after running once, clean glossary 
	Update Language versions to mdtools 2.x:
		- update German version
		- update Hebrew version??
		- update Dutch version
		- update swedish version @done
	Update documentation:
		- move all info from ./slides/slides.md to the documentation tree
		- list all macros
		- list markup (including escapung/unescaping \{\{ \}\}
		- list all filters for the renderer
		- list all glossary renderers (for items and for the full glossary is described) 
		- list relevant config variables are described
		- remove obsolete documents
		- add a page for each renderer
		- set up a separate example project for deckset renderer 
	Index document can be empty:
		As an author I want to have a directory without an index document, so that I have more flexibility for arranging content into different editions. 
		- what about headline levels? Trade-off might be that those would need to be manually aligned?
	Support all editions from one structure:
		Build supporter editon and "normal" editions from the same structure, use a config variable cfg.edition (default: '')
		If information about inclusion and exclusion is stored in structure (and not in the content file itself) the info is visible in one place. Keeping this info in a separate array, not in tags, allows for a simpler design
		Variant A:
			add tags to each section: exclude:editon-A|edition-B include:editon-A|edition-B
			add as literal to section
				id: foobart
				exclude:editon-A|edition-B 
				include:editon-A|edition-B
				sections: …
	Port revealjs renderer to mdtools 2.0:
		At the moment, there are 2 distinct functions, both should be preserved.
			render source as deckset
			convert markdown to deckset
		- remove init in slides, obsolete commands, index and build_web_content
		- add new command stub for converting (also to setup.py)
		- move files to new location
		- find out how both functions interact with each other and update todo list
		- test realjs converter with output of deckset renderer 
		- then convert revealjs renderer
	Fix testsuite:
		- ensure that all existing tests are running
		- check that all main features are not only explained but also used in the documentation so that the documentation serves as a test suite
	Redirections: @estimate(6h)
		As an author, I redirections on my website so that I can re-arrange my content and change titles as I see fit.
		can simply be released when ready
		Also I might want to move my site to a new github page and set up a 404 page that redirects all requests?
		https://stackoverflow.com/questions/503093/how-do-i-redirect-to-another-webpage
		- create first version of redirections.yaml file from structure.yaml
		- add template for redirection files (including requred JS)
		- add configurable build step for generating redirection files from redirections.yaml
		- add search
	Link to Node:
		As a reader I want links to content nodes in the PDF, the EPUB and the all-in-one webpage, so that I can click on references in the text, and especially in the list of patterns.
	
	Sometimes:
		-   full support for YAML metadata in Markdown source files
		MVP: App with GUI:
			As author I want a simple app that converts my stuff to so that I don't have to mess with installation and teh commandline.
			(people would still require to install MacTex, Jekyll, Pandoc etc., though)
			- build a gui (from on I already have probably)
				- select project file
				- select a preset
				-- run | quit
				- log level
				- log output
			- test if pandoc, latexmk or multimarkdown is installed (is mmd necessary at all??)
			- 
			- execute the build
		MVP: Better Document Structure:
			Better Document Structure: @estimate(6h)
				As an author, I want to use identical file names in different folders so that I don't have to use weird workarounds, e.g. when each part starts with an 'overview' .
				- error is raised if both exist at the same time
				- website is published in folders now
				- all indexes and menus are still working
				- update redirections as necessary
				Release: @estimate(2h)
					this release might require moving some files in Crowdin!!! @priority
					- backup all files in crowdin!
					- manually move files in crowdin!!!
					- release
		Add separate template command: @estimate(2h)
			cmd_template is working with new config format 
			requires some thought, because of new config format, running it with full config is a lot of hassle,
			manually handing in translations and variables is also not right for some usecases.
			Therefore it makes sense to wait if this is needed at all, and if so, in what way
		Better glossary and links support for Latex (and other formats): @estimate(4h)
			Make handling glossary and section links more flexible to enable output in PDF
			most of the code is already there, requires some tweaking though.
			- add markdown rendering for emphasis and strong in glossary text
			- render glossary terms as footnotes for LaTeX
			- render section links as clickable links in LaTeX (like in the index)
			- render section links as clickable links in ePub
			Basic Footnoote Renderer for Ebooks:
				replace glossary link with a footnote marker for that glossary term
			Glossary for Epub:
				glossary can be footnotes, or an epub glossary, but epub glossaries don't seem to be universally supported:
					http://www.idpf.org/epub/dict/#sec-1
					https://ebooks.stackexchange.com/questions/2344/epub-kindle-file-glossary-and-dictionary-selection
					https://support.apple.com/kb/PH2753?locale=en_US&viewlocale=en_US
					https://pressbooks.com/blog/our-gifts-to-you-this-holiday-a-new-glossary-feature-customizable-section-labels-and-more/
					https://www.wikihow.com/Write-a-Glossary
			Glossary for PDF:
			Try footnotes, one footnote per glossary entry, or underlining all glossary entries with LaTeX markup (or both)
					dotted underline https://tex.stackexchange.com/questions/27258/how-do-i-write-underline-text-but-with-a-dotted-line
					underlines with ulem: http://texdoc.net/texmf-dist/doc/generic/ulem/ulem.pdf
				undeline in Latex: https://alexwlchan.net/2017/10/latex-underlines/
			- try https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#glossaries
		Support for Open Graph tags:
			simple stuff that goes in the page header, can be configured via _config.yml
			https://en.wikipedia.org/wiki/Facebook_Platform#Open_Graph_protocol
			used by facebook, twitter, google, and linkedin: https://stackoverflow.com/questions/10397510/do-services-other-than-facebook-use-open-graph
Done: @done
	Convert Layout to bootstrap: @done
		use bootstrap 4 first because that works with jQuery and smartmenus, then see about bootstrap5 (which *should* also work)
		- bug: menu button snaps sooner than menu space
		Notes for adaptation in projects:
			- index.html: markup and version text: .small
			- replace all the css!
			- test what happens to plain template (pattern map)
			- make sure texts for prev/next are  added to translation memory
			- make sure page.html is added to contents/website/_layouts and added to projects.yaml
			- make sure to upfate menu.html
		The Basics: @done
			- add bootstrap 4.5.x (css and media query, css below the site) @done
			see https://getbootstrap.com/docs/4.0/getting-started/introduction/
			- add to templates/default.html @done
			- add to plain.html @done
		Clean up CSS: @done
			- update strutude (base / content / layout) and put everything where it needs to be @done
			- check what is still necessary, and what can go @done
			- use bootstrap's clearfix where possible @done
			- fix typography to use bootstrap @done
			- make sure menu uses proper media queries @done
			- check _base.scss for othe obsolete things @done
			- Replace media queries with bootstrap code @done
		Switch to popper.js for tooltips: @done
				https://www.geeksforgeeks.org/bootstrap-4-popover/?ref=lbp
				- add js from https://popper.js.org/ @done
				- replace styles @done
				
		Quick and dirty redesign with bootstrap for a simpler and cleaner look:
			Overview
				Menu on the left border of screen, 
				conten centered and a little wider
				lightboxes for illustriations on desktop so that they don't mess up the pages
				simple nav buttons < > around content or below on mobile
				index.html stays as it is
			- decide about information to keep in footer, where would that go? @done
			- fix icons in menu.html (and add  class="icon") @done
			New Two Column Layout: @done
				- content is centered, but with maximum size (see https://www.geeksforgeeks.org/bootstrap-4-holy-grail-layout/?ref=lbp) @done
				- Header: convert to grid @done
				Footer: @done
					- use grid @done
					-  make it look good @done
					- remove superfluous styles @done
				Menu: @done
					menu on the left side of screen, with a slightly grey background, and a scrollbar 
					search-bar for patterns will come on top above the menu
					menu div gets a scrollbar
					add note: "published with mdtools"
					Smartmenu  bootstrap pugin only works for HORIZONTAL navbar menus!
					smartmenu appears to be working fine as it is
					- style menu @done
					- bug: footer must start below menu at all times!! @done
					- fix menu and content resizing @done
			Fix typography: @done
				- Set base font size @done
				- use .small for footer etc @done
				- remove all superfluous styles @done
			Illustrations: @done
				- Step 1: make  them responsive (simple) @done
					https://www.geeksforgeeks.org/bootstrap-4-images/?ref=lbp
				- Step 2: make them nice (takes a bit more effort) @done
					add lightboxes make sure illustrations don't look like shit because long things are stretched ultrawide
				e.g. https://mdbootstrap.com/docs/b4/jquery/javascript/lightbox/ deactivates on mobile automatically, that's nice
			Cleaner navigation: @done
				keyboard navigation is now broken, because I moved all javascript down the page
				quick and dirty solution: render links with id = "nav-next" and "nav-prev" and grab their url via javascript - BUT prev/next is not part of the content but page metadate and should be added to yaml front matter (will appear as global variables in liquid)
				- make mdbuild add prev/next_page_url and prev/next_page_title to front matter of content @done
				- add < and > as navigation buttons for next/prev (using new icons) @done
				- find a way to add first page to navigation so that 'g n' from the homepage leads somewhere @done
				- setup color and mouseover @done
				- add to bottom of page so that it looks nice enough @done
				- map left and right arrow keys to browse quickly through the pages @done
				- add <link rel="prev"|"next">? to html header? @done
		- bug: the content area is moved to the left slightly @done
	Styling the summary: @done
		The summary should not require formatting in the actual summary to make it stand out.
		- replace strip_summary_tags with summary_format=jekyll/epub/latex/plain (metadata.py!!) @done
		- wrap summary in <p class="well(-sm)> and add styles for page and epub, remove ** @done
		- wrap summary in ** for LaTeX output if it isn't already (because that won't break anything), but a nice box would actualle be the thing to do @done
		- fix tests!!! @done
	MVP 1: New Structure, Menu and CSF: @done
		After the first milestone, the Common Sense Framework can be integrated into the practical guide.
		This release affects crowdin! @priority
		New Project Structure: @estimate(2d) @done
			As author, I want a more flexible and consistent document structure so that I am not limited to a fixed three-part structure (Introduction, Chapters, Appendix)
			Constraint: each section still requires a unique id (filename name) as we don't have folders in the first release @priority
			Can't be released without a new menu for the website, because new content will not be visible @priority
		Responsive Website Menu: @done
			As a website visitor I want a responsive menu that gives me access to all content, so that I can find what I want.
		Release of the Practical Guide: @done
			This release removes dependency of translation to structure.yaml.
			As soon as all new templates are translated, other language versions can be updated, too, the CSF will then be added as an update as soon as it has been translated.
	Linkable Glossary: @done
		Glossary items should instead be rendered as dd tags within a dl (definition list) and they should have anchor links so that one can link such as https://patterns.sociocracy30.org/glossary.html#objection which isn't possible now.
	Show/hide parts of content files dependent on format, preset and edition: @done
		As an author I want to be able to show parts of a file only for specific formats, editions or presets, so my project is easier to maintain.
	Simplified Structure (won't do): @done
		Check that a simplified format for structure (like used in the docs) is still possible
		
		It doesn't appear to be possible. Converting a project to the new structure is simple and well worth the effort.
	Better User Experience for Website: @done
			- add smartmenu keyboard navigation addon @done
			- add keyboard navigation for next page @done
	Update documentation: @done
		Showcase features and document usage of mdtools in a documentation that is created with mdtools
		…
		- copy all necessary stuff (including the makefile) from S3 repo @done
		- setup project yaml from S3 practical guide @done
		- convert filesystem structure @done
		- copy all files from docs folder @done
		- conver structure.yaml @done
		- integrate makefile @done
		- convert all templates @done
		- convert .tex @done
		- convert project.yaml @done
		- convert _config.yml @done
		- convert epub header @done
		- ensure everything inside content/website is updated @done
		- @done
		- attempt quickfix of deckset renderer jsut for fun @done
		- move documentation from /doc-src/en to .content @done
	Port Deckset renderer to mdtools 2.0: @done

processing slides:
	set up basic test for all important formats (gold master): @1h
		make sure all relevant features are covered
		- speaker notes
		- glossary renderer and page breaks (at least 3 glossary entries)
		- inline images
		- section numbering
		- image captions
	reveal.js renderer: @later
		- section links [Governance Facilitator](section:governance-facilitator) : replace with emphasis on title
		- glossary overlays  [Driver](glossary:driver): add html overlay
		- add support for right aligned images
		- have chapter links link to slide https://github.com/hakimel/reveal.js/#internal-links
		- revealjs: add html overlay for glossary terms
		Style/Theming:
			see https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md
			- paragraphs are centered, should be aligned right (.reveal .slides { text-align: center;} 
			- some slides are truncated (affects text-only slides also). Those slides are displayed completely when reducing the screen width
	
mdimg:
	- (optional) parse non-language assets?
	- as of now, using one language only no longer works, this needs to be remedied @priority(high)
	Multi-language Support:
		- document structure in readme or help
			Image repositories structure:
				Assumption: documents may reference images from all languages
				there needs to be a common root for for images "img", which is symlinked into each folder that makes use of the images. Otherwise folders become messy quite soon. 
				- Maybe that root folder can be called something else to cater for something else? If the code is clever, the root folder's name is not important, and image references will be translated accordingly. Then we could also use mdimg to rename the root folder form "img" to, say, "assets"
				/img/
					/de/...
					/en/…
				/slides/
					/de/…
					/en/…