updated readme to be more detailed

README.md

@@ -1,15 +1,24 @@
 # gemlog.sh
 
-Utility for writing and managing gemini logs (gemlogs) without needing cgi.
+Utility for writing and managing gemini logs (gemlogs) and atom feeds without
+needing a cgi script.
 
-To install: put it wherever you want and just add it to path
+To install:
+1. put it wherever you want and just add it to path
+2. make sure you modify `make_globals()` and `build_entries()` in the script to
+   customize it to your gemlog.
 
 To use:
-1. write your post in .gmi format  
+1. Make sure to 
-   the script will display all posts starting with a number in reverse
+2. Write your post in .gmi format. The first header of any level on the page
-   alphabetical order, so I recommend naming your post in the format
+   will be used as a title (it doesn't have to be on the first line). The
-   `YYYY-MM-DD.gmi`. the first heading line of any depth in the document will
+   script will detect any .gmi files that start with a number and assume
-   be used as a title
+   they're blog posts. It'll display them in reverse alphabetical order, so I
-2. make sure you're in your gemlog directory then run `gemlog.sh` to build
+   recommend to name your files like `YYYY-MM-DD.gmi` or
-3. if you want rss, symlink the feed.rss file to your html server directory
+   `YYYY-MM-DD-title-here.gmi` so you get them sorted nicely in reverse
+   chronological order.
+3. make sure you're in your gemlog directory then run `gemlog.sh` to build the
+   index page and the atom feed
+4. if you want your atom feed to be accessible over the web as well as gemini,
+   symlink the atom.xml file to your web server directory
 

gemlog.sh

@@ -15,21 +15,22 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-# fill out variables here
+
+# to customize, modify variables here and modify build_entries()
 make_globals() {
 	global_title="yatg"
 	global_description="yet another tech gemlog"
-	global_url="gemini://nytpu.com/gemlog/" # link to base url of blog
+	global_url="gemini://nytpu.com/gemlog/" # link to base url of gemlog
 	global_author="nytpu"
 	global_author_email="alex@nytpu.com"
-	global_author_url="gemini://nytpu.com/"
+	global_author_url="gemini://nytpu.com/" # homepage of author
 	global_license="CC by"
 
 	gemlog_feed="atom.xml" # filename of the atom feed
-	number_of_feed_articles="50" # number of posts in rss feed
+	number_of_feed_articles="50" # maximum number of posts added to atom feed
 	feed_base_url="https://nytpu.com/files/" # base url that the feed is hosted at
 
-	index="index.gmi" # main page, not recommended to change
+	index="index.gmi" # main page of gemlog, not recommended to change
 
 	# don't change these
 	gemlog_sh_link="https://tildegit.org/nytpu/gemlog.sh"
@@ -74,7 +75,8 @@ EOF
 			printf "</title>\n    <id>$global_url${i#'./'}</id>\n"
 			printf "    <link rel='alternate' href='$global_url${i#'./'}'/>\n    <updated>"
 			echo "$i" | perl -ne '/^(\d{4}-\d{2}-\d{2}).*/; print $1' | date "$date_format_8601" -f - | tr -d '\n'
-			printf "</updated>\n    <summary>You need a gemini protocol client to view this post. If you have one installed, here is the link to the post: $global_url${i#'./'}\"&gt;$global_url${i#'./'}</summary>\n  </entry>\n"
+			# change or remove the <summary></summary> block if you want a different description or no description at all
+			printf "</updated>\n    <summary>You need a gemini client to view this post. If you have one installed, here is the link to the post: $global_url${i#'./'}\"&gt;$global_url${i#'./'}</summary>\n  </entry>\n"
 
 			n=$(( n + 1 ))
 		done < <(ls -r [[:digit:]]*.gmi)
@@ -86,10 +88,10 @@ EOF
 	chmod 644 "$gemlog_feed"
 }
 
-# change this to what you want
 build_entries() {
 	echo "Building entries"
 	{
+		# header of the page (above the posts list)
 		sed 's/$/\r/g' << 'EOF'
 ```yet another tech gemlog (yatg) by nytpu
   ,───────────────.
@@ -110,7 +112,8 @@ EOF
 			pubdate=$(echo $i | perl -ne '/^(\d{4}-\d{2}-\d{2}).*/; print $1')
 			printf "=> $global_url$post $pubdate — $title\r\n"
 		done < <(ls -r [[:digit:]]*.gmi)
-
+		
+		# footer of the page (below the list of posts)
 		printf "\r\n\r\n"
 		printf "=> / go home\r\n"
 		printf "\r\n"
@@ -128,7 +131,8 @@ toot() {
 	read -r -p "do you want to toot the newest post? [y/N] " response
 	if [[ "$response" =~ ^([yY][eE][sS]|[yY])$ ]]
 	then
-		printf "new blog post: ${title}\n\ngemini://nytpu.com/gemlog/${filename}" | toot post 
+		# change this if you want the toot to have different content
+		printf "new gemlog post: ${title}\n\ngemini://nytpu.com/gemlog/${filename}" | toot post 
 	fi
 }