Fixed #28190 -- Clarifed how include/extends treat template names.

[gitanupam]

I feel it is worth re-iterating that the example is using an absolute path and folks should prefix "./" if the template being referenced is in the same directory as the template that is referencing it.

https://code.djangoproject.com/ticket/28190

[timgraham]

I'm not sure if "absolute path" is good terminology to use, considering that the given path is usually relative to the directory specified by a template loader.

Formatting issues:

1. Lines must be wrapped at 80 characters.
2. This is on the same indent level as the code block and so will appear in it.
3. I guess you meant to use "./name_snippet.html" in the example.

A clarification might be better in the discussion of relative paths in the {% extends %} tag:

django/docs/ref/templates/builtins.txt

Lines 218 to 232 in d611a89

	A string argument may be a relative path starting with ``./`` or ``../``. For
	example, assume the following directory structure::
	dir1/
	template.html
	base2.html
	my/
	base3.html
	base1.html
	In ``template.html``, the following paths would be valid::
	{% extends "./base2.html" %}
	{% extends "../base1.html" %}
	{% extends "./my/base3.html" %}

For example, that could be revised to say something like "A string argument may be a relative path to the current template..."

[timgraham]

@gitanupam, do you want to try to amend this as suggested?

[gitanupam]

@timgraham Done (sorry for the delay).

Added the clarification in the 'extends' section and referred to it in the 'include' example.

(was basically thinking from the mindset of the html world where including files/images/etc. are relative to the current directory by default, hence thought a clarification/reminder here might help)

[timgraham]

After looking at your proposal, I thought this might be a simpler approach:

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index daf4f9a..49375e0 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -215,8 +215,9 @@ This tag can be used in two ways:
 
 See :ref:`template-inheritance` for more information.
 
-A string argument may be a relative path starting with ``./`` or ``../``. For
-example, assume the following directory structure::
+Normally the template name is relative to the template loader's root directory.
+A string argument may also be a relative path starting with ``./`` or ``../``.
+For example, assume the following directory structure::
 
     dir1/
         template.html
@@ -674,8 +675,9 @@ This example includes the contents of the template ``"foo/bar.html"``::
 
     {% include "foo/bar.html" %}
 
-A string argument may be a relative path starting with ``./`` or ``../`` as
-described in the :ttag:`extends` tag.
+Normally the template name is relative to the template loader's root directory.
+A string argument may also be a relative path starting with ``./`` or ``../``
+as described in the :ttag:`extends` tag.
 
 This example includes the contents of the template whose name is contained in
 the variable ``template_name``::

[gitanupam]

Agree - your proposal looks better.