img naming convention and organization

[danbjoseph]

In response to Issue #125 a translation workflow guide is being developed.

This pull request contains edits of the English version with the intention of making the process of creating a new translation easier.

images:

• consistent use of reference style image syntax in chapters (previously a mix of reference and inline)
• language subfolder within images folder
• file naming convention:
  en_beg_[two digit chapter #]_
  [chapter name based on permalink]_
  image[two digit # code]_
  [image name based on image reference id]
• {{site.baseurl}} removed from file paths
  • images didn't load for All Chapters on live site
  • this change (when running the site locally) has images loading on the single chapter pages and on the All Chapters page

NOTE: The chapter and image numbers are not a good system and hard to update. But for now, all the files in
"images\en" are being used on the published pages (no old files not being used), the numbers are paired with text descriptors, the files are all in one place, and the organization is consistent (making batch renaming easy with code or any number of utilities).
NOTE: The jekyll liquid filters are still displaying after the last post for All Chapters. Not sure what the fix is.

other (unrelated):

• link in CONTRIBUTING.md updated to skip a redirect

[jeffhaack]

I'm rewriting a bit of the beginner guide and other guides and in the process editing some of the images and trying to organize them.

What do you think about having subfolders for each chapter? They could also be divided by language as you have done here.

You can see what I mean in my fork https://github.com/jeffhaack/learnosm/tree/gh-pages/images/beginner

[danbjoseph]

It's great that you're doing some rewrites. The guide needs to keep up with the changes in the material it covers.

I feel that the images should definitely be organized by language. I think it will help reduce clutter and confusion when new translations are added. In the translation workflow guide I'm working on, I've proposed that one of steps for getting ready is to copy the 'en' images folder and rename it for the new language. This will keep people working on different languages from breaking each other's image links (example being if someone updates and changes the filename of an en version image that is being referenced by another language version). With separate language folders you can clean and update the images folder without worrying about such cross language image dependencies. There will be some duplication across folders (you don't translate an image of an interface icon) but I think the benefit of being able to accurately/correctly/easily remove old image files as they fall out of use for the version you're working on outweighs the duplication. Right now the 'images/en' folder (as I've organized it in this pull request) has only 112 files and the consistent naming convention keeps them nicely sorted. Having them all in one folder also allows you to easily see how the naming convention carries across chapters. The chapter and img name embedded into the filenames make things more readable and make it less confusing/easier to update after something like a chapter reordering.

[jeffhaack]

I agree with the language folders. But can we have separate folders for each chapter? It's quite annoying to edit a chapter when there are hundreds of files in one massive directory. I've just added 10 or so new chapters into an editing section. So I'd like to structure the images like this:

/images/en/beginner/ch1/.png
/images/en/beginner/ch2/.png
/images/en/beginner/ch3/.png
[...]
/images/en/editing/ch1/.png
/images/en/editing/ch2/.png
/images/en/editing/ch3/.png
[...]

Also, I'm not really good with git so I'm not sure how to deal with your pull request. I've made some considerable changes to the posts and images folder already, so if we merge your pull request then there's going to be lots of conflicts in my version. I'd prefer to just adjust it in my fork and then pull in the changes. However, I do want to pull in the changes you've made to other documents here. Any suggestions?

[danbjoseph]

How about I use your repo as an upstream, sync my repo with it, resolve all the conflicts, and commit (so that my pull request incorporates all your changes to date)? I can do it tomorrow morning, Oct-15 EST.

[jeffhaack]

That'd be great, thanks.

[danbjoseph]

Updates to pull request:
All english version images are in 'images/en' and I went ahead and conformed to what @jeffhaack has been doing for the chapter folders. But, I think putting images into folders by chapter is unnecessary. I would support having one folder level below 'en' that divides by guide difficulty (beginner, intermediate, advanced).

• There are chapters with just 2 or 3 images. And most don't have more than a dozen.
• It obscures the higher level naming conventions since you can only compare the difference in the last bit of the filename and not look at cross chapter naming.
• With a consistent naming convention everything you need to know is contained in the filename. There are no dependencies on the containing folder(s) for figuring out how the image fits into the guide. The conventions I've proposed improve the chances of being able to match translated images with the english original/master version. (example, if an image is simply named editor.png and then someone creates urednik.png most people are going to have no idea that the two are the "same" image for different language versions).

en_beg_[two digit chapter #]_
[chapter name based on permalink]_
image[two digit # code]_
[image name based on image reference id]

Issues:

• On the first page, the footer obscures the end of the left-nav-bar because there is not enough content in the right body column to push it down.
• Needs to be an easy way (built into the interface, not using the browser back) to navigate to the beginner's section from the intermediate/advanced sections (editing, map_design, coordination, etc).

[severinmenard]

Hi,

Just my point of view but someone had already mentioned this in the past:
using naming with numbers is really constraining. What about if after
discussion the LearnOSM contributors think that:

• a new chapter should be placed between two existent?
• a new image or screenshot would be valuable to illustrate one paragraph
  within a chapter?

Everything impacted should be then renamed every time?

Sincerely,

Severin

On Tue, Oct 15, 2013 at 4:34 PM, Dan Joseph [email protected]:

Updates to pull request:
All english version images are in 'images/en' and I went ahead and
conformed to what @jeffhaack https://github.com/jeffhaack has been
doing for the chapter folders. But, I think putting images into folders by
chapter is unnecessary. I would support having one folder level below 'en'
that divides by guide difficulty (beginner, intermediate, advanced).

• There are chapters with just 2 or 3 images. And most don't have more
  than a dozen.
• It obscures the higher level naming conventions since you can only
  compare the difference in the last bit of the filename and not look at
  cross chapter naming.
• With a consistent naming convention everything you need to know is
  contained in the filename. There are no dependencies on the containing
  folder(s) for figuring out how the image fits into the guide. The
  conventions I've proposed improve the chances of being able to match
  translated images with the english original/master version. (example, if an
  image is simply named editor.png and then someone creates *
  urednik.png* most people are going to have no idea that the two are
  the "same" image for different language versions).

en_beg_[two digit chapter #]_
[chapter name based on permalink]_
image[two digit # code]_
[image name based on image reference id]

Issues:

• On the first page, the footer obscures the end of the left-nav-bar
  because there is not enough content in the right body column to push it
  down.
• Needs to be an easy way (built into the interface, not using the
  browser back) to navigate to the beginner's section from the
  intermediate/advanced sections (editing, map_design, coordination, etc).

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/134#issuecomment-26339466
.

[danbjoseph]

Yes, in terms of keeping the list of images in the same order which they appear in the chapter, the system falls apart quickly after updates. However, image numbering can be considered an additional identifier and any new images can simply be added onto the end (both in numbering and on the terminal image reference list). Then at least, the reference list (at the end of the code for a chapter) will be in the same order as image files in the folder. Also, if a translator edits the english text in a filename, the numbering can serve as a sort of cross referencing backup.

With a batch rename utility (the one I use is free, and I'm sure there are other options), changing the chapter number is super easy because the chapter numbers always have the same index position.

[jeffhaack]

So, can you help me figure out a little git magic now? What do I need to do to continue working on this repo and make new commits?

Re: image names, it really doesn't matter much to me, I'm happy to migrate to @danbjoseph's suggestions though I find it a bit more convenient just at the moment while making extensive edits to keep separate folders. But I have no problem with your ideas.

@danbjoseph re: your issues - yes, we need to update the navigation for new sections and to always be able get back to the beginner. I was thinking there could be a separate menu below the section menu (maybe different color/style) that lists all the sections besides the current section? I guess there's a jekylly way to do this but I couldn't figure out what it is. And the left nav bar getting cut off is more than just there not being enough content on the page - it still gets cut off for some reason if it is too long, even when the page has plenty of content.

[danbjoseph]

option A

• accept the pull request
• sync your repo with the hotosm repo

option B

• follow the instructions for syncing a fork to update your local branch with the same changes contained in my pull request without yet adding any of the changes to the hotosm repo

git remote add upstream https://github.com/danbjoseph/learnosm.git
git fetch upstream
git checkout gh-pages
git merge upstream/gh-pages

[nebulon42]

Regarding the issue with footer obscuring nav box:

• when there is not enough content: .doc-main needs a bigger min-height, since the height of the nav box is apparently changing this should be set dynamically with Javascript
• when there is plenty of content: pull request Fixed issues with sticky nav and mobile version #135 should fix this.

[harry-wood]

So given this file is in place here now :
images/en/beginner/01_introduction/en_beg_01_introduction_image00_village-in-indonesia.png
(with the referencing _post file modded accordingly)

Any reason we didn't delete it from here?
images/en_beg_ch1_image00.png

[danbjoseph]

Sometime soon I plan on going through the existing language translations to check for unexpected image dependencies. Probably do at least some high level folder organization (like division at least into language folders). And continue working on cleaning up the images folder.

[jeffhaack]

Yah, I left all the original images in place just in case the other languages are depending on them. There should be a new langauge folder for all the languages, and the references in the posts modified accordingly. Then these orginal images can be removed.