Skip to content

Latest commit

 

History

History
347 lines (276 loc) · 16.9 KB

README-ar.md

File metadata and controls

347 lines (276 loc) · 16.9 KB
Raw

بسم الله الرحمن الرحيم

الحمدُ لله ربِّ العالمينْ، والصلاةُ والسلام على رسوله الأمينْ، وعلى آله وصحبه أجمعينْ، ومن تبعهم بإحسانٍ إلى يوم الدين، وبعد:

فهذا حديثٌ يَّـسيرٌ عن تطبيق أدواتِ الملفاتِ المبدأفةِ، نفع اللهُ به وبارك فيه، وتقـبّـله بقَبولٍ حسنٍ. اللهم آمين.

pdftools

Version Tests Downloads/week Downloads/month Downloads/total

برنامجٌ لِّاستخراج الصفَحاتِ من الملفات المبدأفةِ، أو لجمع عدّةِ ملفاتٍ في ملفٍ وَّاحدٍ مع إمكانيةِ اختيارِ بعضِ الصفحاتِ من كل ملف.

يوفر البرنامج برنامجَينِ متـشابهَـيـنِ لاستعمالهما في سطر الأوامر: pdftools و pdf-tools.

يمكن استعمال البرنامج لتغيير معلومات الملف المبدأف عند استعمال الأمر معالجة الملف process ، انظر الملف test/docs/example.yaml للتفاصيل.

متطلبات البرنامج

إذا كنت تعرف برنامجا أو مكتبة برمجية أفضل مما أستعمله فأرجو أن تدلني عليها: https://github.com/bader-nasser/pdftools/issues

لماذا البرنامج بالإنجليزية؟

يستعمل البرنامج برنامجًـا آخـرَ لتوفير أغلبِ الخصائصِ اللازمة كي يؤديَ وظائـفَـه، وهْـو باللغة الإنجليزية. انظر https://oclif.io

ودعمُ اللغةِ العربيةِ أو اللغاتِ التي تُكتبُ من اليمين إلى الشمال في برامج سطر الأوامر يكاد يكونُ معدومًا أو سيئًـا!

لماذا البرنامج بدون واجهة؟

أحتاج شخصيا إلى برنامجٍ سهلٍ يقوم بهذين الأمرينِ الهامَّينِ عندي:

  • إمّا أن أُعطـيَـه اسمَ الملفِ المبدأفِ (أو مكان وجوده في الجهاز)، وملفا آخر فيه الصفحات التي أرغب في استخراجها منه، فيستخرجَها
  • أو أن أعطيَـه ملفا واحدا فقط فيه إشارة إلى الملفات التي أود منه أن يجمعَها في ملفٍ وَّاحدٍ، بالصفحات التي أرغب فيها من كل ملف، فيجمعَـها

بدون أن أضطر إلى استعمالِ واجهةٍ أو أزرارٍ أو تطويلٍ في العملية. وإذا تعامل البرنامجُ مع ملفٍ نَـصّيٍّ فيه كلمة شارك بالإنجليزية، أنشأ لي ملفينِ اثنينِ! مع القيام ببعض الأمور الأقل أهمية كما سيتبين لاحقا.

فكتابة مثل هذه الأسطر أسهل وأسرع وأنفع من استعمال الواجهةِ الرسوميةِ والضغطِ على الأزرار:

pdftools extract -i relative/path/to/input.pdf -o /absolute/path/to/output.pdf --data datafile.txt

pdftools e -i /absolute/path/in.pdf -o ../relative/path/out --compress --pageRanges "5, 9-3even, end, 1south"

pdf-tools process file.yml # .json/.json5/.yaml/.yml/.toml

ملحوظة: يُضغط زر الإدخال Enter بعد كل سطر

ملحوظة أخرى: الملفات التي يتعامل معها البرامج هي ملفات نصية وليست مستنداتٍ، لذا ينبغي أن تُستعملَ برامجُ تحريرِ النصوصِ للتعامل معها لا برامجُ تحريرِ المستنداتِ.

برامج تحريرِ النصوصِ من مثل:

  • Visual Studio Code
  • Sublime Text
  • notepad++
  • gedit
  • notepad
    • وجدتُّه سيئا في عرض ملف الـ JSON

وبرامج تحرير المستندات من مثل:

  • Microsoft Office (Word)
  • LibreOffice

وحسَب علمي القاصر فهْـي لا تصلح للتعامل مع الملفاتِ النصيةِ.

كيف يمكن التعامل مع سطر الأوامر؟

  • لمستخدمي أنظمةِ لِيـنِكْسَ وماك، ابحثْ عن التطبيق: Terminal
  • لمستخدمي الإصدارِ الثامنِ من نِّـظـامِ وندزَ -ولعل هذا يصلح للإصدارات الحديثة-، افتحِ المجلدَ الذي فيه الملفُ المبدأفُ، أوِ المجلدَ الذي تريد أن تحفظَ ناتجَ البرنامجِ فيه، أو أيَّ مجلدٍ كان، ثم اضغطْ -في أي مكانٍ فارغٍ أو على المجلد- الزرينِ: زرِ (شِفتَ) SHIFT والزرِ الأيمنِ للفأرة في نفس الوقتِ، ثم اختر Open command window here ، ولعلها قد عُرّبت إلى: افتح نافذة الأوامر هنا!

لكن لعل الأفضلَ لمستخدمي وندزَ تثبيتُ برنامجِ git ، ثم اختيارُ Open Git bash here من القائمةِ الظاهرةِ بعد الضغط على الزرين: الزرِ الأيمن للفأرة و(شِفت) كما تقدم ذكره!

ملحوظة: لا حاجةَ لاستعمال حسابِ مديرِ النظامِ لتشغيل نافذةِ سطرِ الأوامرِ.

ملحوظة أخرى: بإمكانك سحبُ الملفِ المبدأفِ -أوِ المجلدِ- إلى برنامج سطرِ الأوامرِ، وهذا سوف ينسخ لك مكانَ وُجودِه!

للتنقل بين المجلدات، استعمل الأمر cd ، ولعرض محتويات المجلد، استعمل الأمر ls أو dir

cd "C:/user/path to directory"
cd ~/home/path
ls -l
ls -la
dir

أو باختصارٍ، اضغطْ على زر ابدأ، ثم ابحث عن سطر الأوامرِ أو git bash أو power shell أو cmd أو command prompt أو terminal

كيف أثبت البرنامج في الحاسوب؟

  1. ثـبّـتْ متطلباتِ البرنامجِ
  2. افتحْ واجهةَ سطرِ الأوامرِ
  3. اُكتُبِ السطرَ التاليَ ثم اضغطْ زرَّ الإدخالِ وانتظرْ قليلًا:
npm i -g @bader-nasser/pdftools
  1. بإمكانك الآنَ استعمالُ البرنامجِ والاطلاعُ على رسائل المساعدةِ بكتابة أيِّ أمرٍ مِّـمّا يلي، والضغطِ على زر الإدخال:
pdftools help
pdf-tools help extract
pdftools help process

ملحوظة: بإمكانك استعمالُ برنامج Yarn أو pnpm لتثبيت البرنامج، ورَغم أني أستعمل pnpm لكنني واجهت بعضَ المشاكلِ عند استخدامِه فلا أستطيعُ أن أُوصيَ به أو بغيره. وحسْبيْ َ أن أدلَّ عليه!

كيف أُحدِّث البرنامج؟

استعمل نفس الأمر الذي استعملته لتثبيته:

npm i -g @bader-nasser/pdftools

ملحوظة: لتسهيل تحديثِ هذا البرنامجِ مع غيرِه من البرامج التي ثبتّها باستعمال npm استعملِ الأمرَ:

npm i -g

كيف أحذف البرنامج؟

npm uninstall -g @bader-nasser/pdftools

كيف أستعمل البرنامج؟

  • افتح واجهة سطر الأوامر

  • انتقل إلى المجلد الذي فيه الملف المبدأف الذي تود التعامل معه، أو المجلد الذي تريد حفظ ناتج البرنامج فيه، أو لا تنتقل إلى أي مكان فالأمر متروك إليك :)

    للتنقل بين المجلدات، استعمل الأمر cd ثم اكتب بعده مكان المجلد المطلوب، مثلا:

cd C:\users\your-name\downloads

وإذا كان مسار المجلد فيه مسافة فأحطه بعلامتي التنصيص هكذا:

cd "C:\users\your name\downloads"

  • اضغط زر الإدخال بعد كل أمر من الأوامر!

  • ملحوظة: في وندز، إذا أردتَّ نسخَ مكانِ الملفِ دون كتابته بنفسك في نافذة سطر الأوامر، فاضغط على (الملف) باستعمال الزرين: الزر الأيمن للفأرة وزر (شفت) ثم اختر: Copy as path ولعلها تُرجمت إلى: انسخ كمسار، أو انسخ مكان الملف! ثم استعمل زر الفأرة الأيمن للصق مكانِ الملفِ في نافذة سطرِ الأوامرِ.

  • لاستخراج الصفحات من ملف معين استعمل أحد هذه الأوامر أو جربها كلها:

  • ملحوظة أخرى: الأمر (استخراج الصفحات) له عدة اختصارات وهي: extract, ext, ex, e

# هذا تعليق -وليس أمرا- يبدأ بعلامة الوسم أو المربع
# استخرج الصفحة الأولى من الملف input.pdf
# واحفظ الناتج في الملف output.pdf
# ملحوظة: يضيف البرنامج بعض التغييرات على اسم الملف،
# وفي هذا الأمر، سيكون اسم الملف الناتج output-0001.pdf
# فإذا أردتَّ المحافظة على اسم الملف، فـأضف --keep أو -k إلى الأمر!
# بإمكانك استعمال -f أو -l لاستخراج صفحة واحدة
# -f OR --firstPage
# -l أو --lastPage
pdftools e --input input.pdf --output output.pdf -f 1 --keep
# وإذا أردتَّ تقليل حجمِ الملف فأضف:
# -c أو --compress

# استخرج الصفحات من 1 إلى 3
# من الملف input.pdf
# واحفظ الناتج في ملف output.pdf
# داخل مجلد files في نفس المكان الذي تستعمل فيه البرنامج
# ملحوظة: إذا كان مجلد الناتج غير موجود فالبرنامج سينشئه من أجلك
pdf-tools ex -i input.pdf -o files/output.pdf -f 1 -l 3

# استعمل الملف input.pdf
# الموجود داخل مجلد files في نفس المكان الذي تستعمل فيه البرنامج
# واستخرج الصفحات من 9 إلى 5
# ملحوظة: البرنامج يقبل استعمال الترتيب التصاعدي والتنازلي،
# واستعمال كلمة end للدلالة على آخر صفحة،
# أو r2 للدلالة على الصفحة الثانية من الأخير، وغيرها
# انظر: https://github.com/bader-nasser/pdftools/blob/main/test/docs/data-ar.txt
# واضغط حجم الملف، وأضف كلمة (compress) إلى اسم الملف الناتج
# -c OR --compress
# ولعلك ترغب في استعمال موقع https://www.ilovepdf.com/compress_pdf لتقليل حجم الملف أكثر!
# وأدر الصفحات إلى اليسار
# مع اختيار الصفحات الزوجية فقط!
pdftools ext -i files/input.pdf -o output.pdf -f 9 -l 5 -c -r left -q even

# استخرج الصفحات من 1 إلى 3
# ثم الصفحة 5 وأدرها إلى جهة الشرق
# ثم الصفحات الفردية من 7 إلى 4
# -p OR --pageRanges
pdf-tools ex -i input.pdf -o output.pdf -p "1-3, 5east, 7-4odd"

# استعمل ملف input.pdf
# الموجود في المجلد السابق للمجلد الذي تستعمل فيه البرنامج
# النقطتان تعني: أنك تريد من البرنامج البحث في مكان يسبق المكان الحالي للبرنامج
# واستخرج الصفحات حسَب ما كُتب في ملف test/docs/data-ar.txt
# واعمل بصمت أيها البرنامج بدون إظهار أي رسالة إلا أن يكون هناك خطأ ما!
# -s OR --silent
pdftools e -i ../input.pdf -o output.pdf --data test/docs/data-ar.txt -s

انظر test/docs/data-ar.txt

  • أوِ استعملِ الأمرَ الثانيَ وهو process (واختصارا p) لضمِّ عدة ملفاتٍ مَّعًـا، ولاختيار بعضِ الصفحاتِ من كل ملف:
pdftools process test/docs/data.json

يمكنك كتابة ملف البيانات بلغة JSON5 أو YAML أو TOML. وهذا شرح يسير للملف إذا كان بلغة JSON:

// هذا تعليق **لم يعد** يخرب البرنامج فلا بأس بتركه
// يبدأ الملف بهذا القوس المعوج
{
	// هذا السطر صار مفيدا للمساعدة في كتابة الملف
	// ستظهر بعض التعليمات بالإنجليزية عند استخدام البرامج التي تفهم فائدة مثل هذا السطر
	// https://json-schema.org/implementations.html#editors
	$schema: 'https://github.com/bader-nasser/pdftools/raw/main/data.schema.json',
	//  اكتب هنا مكان الملف الناتج بالنسبة إلى هذا الملفِ
	// النقطتان تعني: اخرج من هذا المجلد، واذهب إلى مجلد pdfs بجانب المجلد الذي فيه ملف البيانات
	// واحفظ الناتج باسم output.pdf
	// ملحوظة: الناتج قد يكون فيه كلمات أخرى!
	output: '../pdfs/output.pdf',
	// ملحوظة أخرى: في نظام وندز: غيّر الشرطة المائلة إلى جهة اليسار إلى شرطتين اثـنـتين:
	// C:\users\your-name\downloads\file.pdf => C:\\users\\your-name\\downloads\\file.pdf
	// أو اجعلها مائلة إلى جهة اليمين
	// C:\users\your-name\downloads\file.pdf => C:/users/your-name/downloads/file.pdf
	// أمثلة لمكان الملف الناتج:
	// "output": "pdfs/output.pdf",
	// "output": "/absolute/path/to/pdfs/output.pdf",
	// "output": "C:\\users\\your-name\\downloads\\output.pdf",
	// هذه حقل اختياري
	// اضغط حجم الملف، وأضف كلمة compress إلى الاسم
	// ولعلك ترغب في استعمال موقع https://www.ilovepdf.com/compress_pdf لتقليل حجم الملف أكثر!
	compress: true,
	// هذا حقل اختياري أيضا
	// يا برنامج، اسكت ولا تُظهر لي تعليقات تبين ما تفعله
	silent: true,
	// هذا حقل اختياري أيضا
	// تظاهر أنك تفعل شيئا!
	dryRun: true,
	// الملفات التي تشكل الناتج النهائي
	files: [
		// استعمل الملف input-1.pdf كاملا
		// الملف محفوظ في مجلد باسم pdfs وهو بجانب المجلد الذي فيه ملف البيانات لأنه يبدأ بنقطتين
		'../pdfs/input-1.pdf',
		{
			// استعمل الملف input-2.pdf
			// وهو محفوظ في مجلد باسم pdfs بجانب ملف البيانات
			name: 'pdfs/input-2.pdf',
			// ولكني أريد الصفحة الثانية فقط
			pages: 2,
		},
		{
			// استعمل هذا الملف المحفوظ في هذا المكان المحدد
			name: 'C:\\users\\your-name\\downloads\\file.pdf',
			// واستخرج منه الصفحات من 4 إلى 6
			pages: '4-6',
		},
		{
			name: '../pdfs/input-3.pdf',
			// استخرج هذه الصفحات
			// وافصل بين المدخَـلات باستعمال الفاصلة الإنجليزية ,
			// تُكتب المدخلات بنفس الطريقة التي يُكتب بها ملف البيانات المستعمل في الأمر استخراج، وانظر الملف للتفاصيل:
			// https://github.com/bader-nasser/pdftools/blob/main/test/docs/data-ar.txt
			// ولكنها تُحاط بعلامتي تنـصيص إلا أن تكون رقما
			pages: [1, '3', ' 4 -6', '8 - 11odd ', 'end - r5', '2- 5even, 14'],
		},
		{
			name: '../pdfs/input-3.pdf',
			// استعمل هذا الملف لاستخراج الصفحات
			// وهو محفوظ في نفس المجلد الذي فيه ملف البيانات data.json
			data: 'data.txt',
		},
	],
}

رجاء

إذا استـفـدتَّ من البرنامج فـدُلَّ عليه الناسَ حتى يعُـمَّ النفعُ، والدالُّ على الخير كفاعله.